@pleri/olam-cli 0.1.104 → 0.1.106

package/dist/index.js

@@ -487,8 +487,8 @@ var init_parseUtil = __esm({
     init_errors();
     init_en();
     makeIssue = (params) => {
-      const { data, path: path50, errorMaps, issueData } = params;
-      const fullPath = [...path50, ...issueData.path || []];
+      const { data, path: path52, errorMaps, issueData } = params;
+      const fullPath = [...path52, ...issueData.path || []];
       const fullIssue = {
         ...issueData,
         path: fullPath
@@ -796,11 +796,11 @@ var init_types = __esm({
     init_parseUtil();
     init_util();
     ParseInputLazyPath = class {
-      constructor(parent, value, path50, key) {
+      constructor(parent, value, path52, key) {
         this._cachedPath = [];
         this.parent = parent;
         this.data = value;
-        this._path = path50;
+        this._path = path52;
         this._key = key;
       }
       get path() {
@@ -4281,7 +4281,7 @@ import YAML from "yaml";
 function bootstrapStepCmd(entry) {
   return typeof entry === "string" ? entry : entry.cmd;
 }
-function refineForbiddenKeys(value, path50, ctx, rejectSource) {
+function refineForbiddenKeys(value, path52, ctx, rejectSource) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     return;
   }
@@ -4289,12 +4289,12 @@ function refineForbiddenKeys(value, path50, ctx, rejectSource) {
     if (FORBIDDEN_KEYS.has(key)) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
-        path: [...path50, key],
+        path: [...path52, key],
         message: `forbidden key "${key}" (prototype-pollution surface)`
       });
       continue;
     }
-    if (rejectSource && path50.length === 0 && key === "source") {
+    if (rejectSource && path52.length === 0 && key === "source") {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path: ["source"],
@@ -4302,21 +4302,21 @@ function refineForbiddenKeys(value, path50, ctx, rejectSource) {
       });
       continue;
     }
-    refineForbiddenKeys(value[key], [...path50, key], ctx, false);
+    refineForbiddenKeys(value[key], [...path52, key], ctx, false);
   }
 }
-function rejectForbiddenKeys(value, path50, rejectSource) {
+function rejectForbiddenKeys(value, path52, rejectSource) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     return;
   }
   for (const key of Object.keys(value)) {
     if (FORBIDDEN_KEYS.has(key)) {
-      throw new Error(`[manifest] ${path50}: forbidden key "${key}" (prototype-pollution surface)`);
+      throw new Error(`[manifest] ${path52}: forbidden key "${key}" (prototype-pollution surface)`);
     }
     if (rejectSource && key === "source") {
-      throw new Error(`[manifest] ${path50}: top-level "source" is loader-stamped \u2014 manifests must not author it`);
+      throw new Error(`[manifest] ${path52}: top-level "source" is loader-stamped \u2014 manifests must not author it`);
     }
-    rejectForbiddenKeys(value[key], `${path50}.${key}`, false);
+    rejectForbiddenKeys(value[key], `${path52}.${key}`, false);
   }
 }
 function unknownTopLevelKeys(parsed) {
@@ -5309,8 +5309,8 @@ var init_client = __esm({
           throw new Error(`failed to report rate-limit for ${accountId} (HTTP ${res.status})`);
         }
       }
-      async request(method, path50, body, attempt = 0) {
-        const url = `${this.baseUrl}${path50}`;
+      async request(method, path52, body, attempt = 0) {
+        const url = `${this.baseUrl}${path52}`;
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeoutMs);
         const headers = {};
@@ -5328,7 +5328,7 @@ var init_client = __esm({
         } catch (err) {
           if (attempt < RETRY_COUNT && isTransient(err)) {
             await sleep(RETRY_BACKOFF_MS * (attempt + 1));
-            return this.request(method, path50, body, attempt + 1);
+            return this.request(method, path52, body, attempt + 1);
           }
           throw err;
         } finally {
@@ -6877,8 +6877,8 @@ var init_provider3 = __esm({
       // -----------------------------------------------------------------------
       // Internal fetch helper
       // -----------------------------------------------------------------------
-      async request(path50, method, body) {
-        const url = `${this.config.workerUrl}${path50}`;
+      async request(path52, method, body) {
+        const url = `${this.config.workerUrl}${path52}`;
         const bearer = await this.config.mintToken();
         const headers = {
           Authorization: `Bearer ${bearer}`
@@ -8170,8 +8170,8 @@ import { execFileSync as execFileSync3 } from "node:child_process";
 import * as fs14 from "node:fs";
 import * as os9 from "node:os";
 import * as path15 from "node:path";
-function expandHome(p, homedir27) {
-  return p.replace(/^~(?=$|\/|\\)/, homedir27());
+function expandHome(p, homedir28) {
+  return p.replace(/^~(?=$|\/|\\)/, homedir28());
 }
 function sanitizeRepoFilename(name) {
   const sanitized = name.replace(/[^A-Za-z0-9._-]/g, "_");
@@ -8194,7 +8194,7 @@ ${stderr}`;
 }
 function snapshotBaselineDiff(repos, workspacePath, deps = {}) {
   const exec = deps.exec ?? ((cmd, args, opts) => execFileSync3(cmd, args, opts));
-  const homedir27 = deps.homedir ?? (() => os9.homedir());
+  const homedir28 = deps.homedir ?? (() => os9.homedir());
   const baselineDir = path15.join(workspacePath, ".olam", "baseline");
   try {
     fs14.mkdirSync(baselineDir, { recursive: true });
@@ -8210,7 +8210,7 @@ function snapshotBaselineDiff(repos, workspacePath, deps = {}) {
       continue;
     const filename = `${sanitizeRepoFilename(repo.name)}.diff`;
     const outPath = path15.join(baselineDir, filename);
-    const repoPath = expandHome(repo.path, homedir27);
+    const repoPath = expandHome(repo.path, homedir28);
     if (!fs14.existsSync(repoPath)) {
       writeBaselineFile(outPath, `# repo: ${repo.name}
 # (skipped: path ${repoPath} does not exist)
@@ -13822,10 +13822,10 @@ async function readHostCpToken2() {
   if (!fs25.existsSync(tp)) return null;
   return fs25.readFileSync(tp, "utf-8").trim();
 }
-async function callHostCpProxy(method, worldId, path50, body) {
+async function callHostCpProxy(method, worldId, path52, body) {
   const token = await readHostCpToken2();
   if (!token) return { ok: false, status: 0, error: "no token (host CP not started)" };
-  const url = `http://127.0.0.1:${HOST_CP_PORT}/api/world/${encodeURIComponent(worldId)}${path50}`;
+  const url = `http://127.0.0.1:${HOST_CP_PORT}/api/world/${encodeURIComponent(worldId)}${path52}`;
   try {
     const headers = {
       Authorization: `Bearer ${token}`
@@ -14710,9 +14710,9 @@ var UnknownArchetypeError = class extends Error {
 };
 var ArchetypeCycleError = class extends Error {
   path;
-  constructor(path50) {
-    super(`Archetype inheritance cycle detected: ${path50.join(" \u2192 ")} \u2192 ${path50[0] ?? "?"}`);
-    this.path = path50;
+  constructor(path52) {
+    super(`Archetype inheritance cycle detected: ${path52.join(" \u2192 ")} \u2192 ${path52[0] ?? "?"}`);
+    this.path = path52;
     this.name = "ArchetypeCycleError";
   }
 };
@@ -15082,6 +15082,12 @@ async function runBootstrap2(opts, deps = {}) {
   if (digests["mcp-auth"]) {
     imageRefs.push({ name: "mcp-auth", ref: `${registry}/olam-mcp-auth@${digests["mcp-auth"]}` });
   }
+  if (digests["devbox-base"]) {
+    imageRefs.push({
+      name: "devbox-base",
+      ref: `${registry}/olam-devbox@${digests["devbox-base"]}`
+    });
+  }
   const pullSpinner = ora(`Pulling images (${imageRefs.length} parallel)`).start();
   const pullStart = Date.now();
   const pullResults = await Promise.all(
@@ -15111,7 +15117,7 @@ async function runBootstrap2(opts, deps = {}) {
       summary: `pull failed: ${failed.map((r) => r.name).join(", ")}`
     };
   }
-  pullSpinner.succeed(`Pulled 3 images in ${pullElapsed}s`);
+  pullSpinner.succeed(`Pulled ${imageRefs.length} images in ${pullElapsed}s`);
   const handshakeSpinner = ora("Verifying olam.protocol.versions handshake").start();
   for (const { name, ref } of imageRefs) {
     const inspect = await docker2.inspectLabel(ref, "olam.protocol.versions");
@@ -15149,6 +15155,15 @@ async function runBootstrap2(opts, deps = {}) {
   if (mcpAuthRef) {
     tagPlan.push({ name: "mcp-auth", from: mcpAuthRef.ref, to: "olam-mcp-auth:local" });
   }
+  const devboxBaseRef = imageRefs.find((r) => r.name === "devbox-base");
+  if (devboxBaseRef) {
+    tagPlan.push({ name: "devbox-base (bare)", from: devboxBaseRef.ref, to: "olam-devbox:base" });
+    tagPlan.push({
+      name: "devbox-base (registry)",
+      from: devboxBaseRef.ref,
+      to: `${registry}/olam-devbox:base`
+    });
+  }
   for (const { name, from, to } of tagPlan) {
     const result = await docker2.tag(from, to);
     if (result.exitCode !== 0) {
@@ -16078,9 +16093,9 @@ function formatFreshnessWarning(result, image = DEFAULT_DEVBOX_IMAGE) {
     "These source files have changed since the image was built; the",
     "changes will NOT take effect in fresh worlds until you rebuild:"
   ];
-  for (const { path: path50, mtimeMs } of result.newerSources) {
+  for (const { path: path52, mtimeMs } of result.newerSources) {
     const when = new Date(mtimeMs).toISOString();
-    lines.push(`  \u2022 ${path50}  (modified ${when})`);
+    lines.push(`  \u2022 ${path52}  (modified ${when})`);
   }
   lines.push("");
   lines.push("Rebuild with:");
@@ -16239,15 +16254,15 @@ init_host_cp();
 var HOST_CP_URL = "http://127.0.0.1:19000";
 async function readHostCpTokenForCreate() {
   try {
-    const { default: fs48 } = await import("node:fs");
+    const { default: fs50 } = await import("node:fs");
     const { default: os28 } = await import("node:os");
-    const { default: path50 } = await import("node:path");
-    const tp = path50.join(
-      process.env.OLAM_HOME ?? path50.join(os28.homedir(), ".olam"),
+    const { default: path52 } = await import("node:path");
+    const tp = path52.join(
+      process.env.OLAM_HOME ?? path52.join(os28.homedir(), ".olam"),
       "host-cp.token"
     );
-    if (!fs48.existsSync(tp)) return null;
-    return fs48.readFileSync(tp, "utf-8").trim();
+    if (!fs50.existsSync(tp)) return null;
+    return fs50.readFileSync(tp, "utf-8").trim();
   } catch {
     return null;
   }
@@ -16610,12 +16625,12 @@ function defaultNameFromPrompt(prompt) {
 }
 async function readHostCpToken3() {
   try {
-    const { default: fs48 } = await import("node:fs");
+    const { default: fs50 } = await import("node:fs");
     const { default: os28 } = await import("node:os");
-    const { default: path50 } = await import("node:path");
-    const tp = path50.join(os28.homedir(), ".olam", "host-cp.token");
-    if (!fs48.existsSync(tp)) return null;
-    const raw = fs48.readFileSync(tp, "utf-8").trim();
+    const { default: path52 } = await import("node:path");
+    const tp = path52.join(os28.homedir(), ".olam", "host-cp.token");
+    if (!fs50.existsSync(tp)) return null;
+    const raw = fs50.readFileSync(tp, "utf-8").trim();
     return raw.length > 0 ? raw : null;
   } catch {
     return null;
@@ -20346,11 +20361,11 @@ function zodIssueToError(issue, doc, lineCounter) {
     suggestion: deriveSuggestion(issue)
   };
 }
-function formatJsonPath(path50) {
-  if (path50.length === 0)
+function formatJsonPath(path52) {
+  if (path52.length === 0)
     return "<root>";
   let out = "";
-  for (const seg of path50) {
+  for (const seg of path52) {
     if (typeof seg === "number") {
       out += `[${seg}]`;
     } else {
@@ -20359,11 +20374,11 @@ function formatJsonPath(path50) {
   }
   return out;
 }
-function resolveYamlLocation(path50, doc, lineCounter) {
+function resolveYamlLocation(path52, doc, lineCounter) {
   let bestLine = 0;
   let bestColumn = 0;
-  for (let depth = path50.length; depth >= 0; depth -= 1) {
-    const segment = path50.slice(0, depth);
+  for (let depth = path52.length; depth >= 0; depth -= 1) {
+    const segment = path52.slice(0, depth);
     try {
       const node = doc.getIn(segment, true);
       if (node && typeof node === "object" && "range" in node) {
@@ -20581,11 +20596,11 @@ function topoSort(nodes) {
 }
 function traceCycle(start, byId) {
   const seen = /* @__PURE__ */ new Set();
-  const path50 = [];
+  const path52 = [];
   let current = start;
   while (current && !seen.has(current)) {
     seen.add(current);
-    path50.push(current);
+    path52.push(current);
     const node = byId.get(current);
     const next = node?.dependsOn[0];
     if (next === void 0)
@@ -20593,10 +20608,10 @@ function traceCycle(start, byId) {
     current = next;
   }
   if (current && seen.has(current)) {
-    const idx = path50.indexOf(current);
-    return [...path50.slice(idx), current];
+    const idx = path52.indexOf(current);
+    return [...path52.slice(idx), current];
   }
-  return path50;
+  return path52;
 }
 
 // ../core/dist/executor/types.js
@@ -25767,8 +25782,8 @@ var SECRET = process.env["OLAM_MCP_AUTH_SECRET"] ?? "";
 function authHeaders() {
   return SECRET ? { "X-Olam-Mcp-Secret": SECRET } : {};
 }
-async function apiFetch(path50, init = {}) {
-  const res = await fetch(`${BASE_URL}${path50}`, {
+async function apiFetch(path52, init = {}) {
+  const res = await fetch(`${BASE_URL}${path52}`, {
     ...init,
     headers: {
       "Content-Type": "application/json",
@@ -26346,8 +26361,8 @@ function registerMcp(program2) {
 
 // src/commands/kg-build.ts
 import { spawnSync as spawnSync14 } from "node:child_process";
-import fs46 from "node:fs";
-import path48 from "node:path";
+import fs48 from "node:fs";
+import path50 from "node:path";
 
 // ../core/dist/kg/storage-paths.js
 import { homedir as homedir26 } from "node:os";
@@ -26380,17 +26395,17 @@ function kgRoot() {
 function worldsRoot() {
   return join48(olamHome3(), "worlds");
 }
-function assertWithinPrefix(path50, prefix, label) {
-  if (!path50.startsWith(prefix + "/")) {
-    throw new Error(`${label} escape: ${path50} not under ${prefix}/`);
+function assertWithinPrefix(path52, prefix, label) {
+  if (!path52.startsWith(prefix + "/")) {
+    throw new Error(`${label} escape: ${path52} not under ${prefix}/`);
   }
 }
 function kgPristinePath(workspace) {
   validateWorkspaceName(workspace);
   const root = kgRoot();
-  const path50 = resolve10(join48(root, workspace));
-  assertWithinPrefix(path50, root, "kgPristinePath");
-  return path50;
+  const path52 = resolve10(join48(root, workspace));
+  assertWithinPrefix(path52, root, "kgPristinePath");
+  return path52;
 }
 var KG_PATHS_INTERNALS = Object.freeze({
   olamHome: olamHome3,
@@ -26400,10 +26415,394 @@ var KG_PATHS_INTERNALS = Object.freeze({
 
 // src/commands/kg-build.ts
 init_output();
+
+// src/commands/kg-status.ts
+import fs46 from "node:fs";
+import { homedir as homedir27 } from "node:os";
+import path48 from "node:path";
+init_output();
+var SOFT_CAP_BYTES = 15e8;
+var HARD_CAP_BYTES = 5e9;
+function olamHome4() {
+  return process.env.OLAM_HOME ?? path48.join(homedir27(), ".olam");
+}
+function kgRoot2() {
+  return path48.join(olamHome4(), "kg");
+}
+function worldsRoot2() {
+  return path48.join(olamHome4(), "worlds");
+}
+function dirSizeBytes(dir) {
+  if (!fs46.existsSync(dir)) return 0;
+  let total = 0;
+  const stack = [dir];
+  while (stack.length > 0) {
+    const cur = stack.pop();
+    let entries;
+    try {
+      entries = fs46.readdirSync(cur, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path48.join(cur, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      try {
+        total += fs46.statSync(full).size;
+      } catch {
+      }
+    }
+  }
+  return total;
+}
+function formatBytes4(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  if (n < 1024 * 1024 * 1024) return `${(n / 1024 / 1024).toFixed(1)} MB`;
+  return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+function readFreshness(workspace) {
+  const file = path48.join(kgPristinePath(workspace), "freshness.json");
+  if (!fs46.existsSync(file)) return null;
+  try {
+    const raw = JSON.parse(fs46.readFileSync(file, "utf-8"));
+    if (raw && typeof raw === "object") return raw;
+    return null;
+  } catch {
+    return null;
+  }
+}
+function readOverlayNodeCount(graphifyOutDir) {
+  const graphPath = path48.join(graphifyOutDir, "graph.json");
+  if (!fs46.existsSync(graphPath)) return null;
+  try {
+    const raw = JSON.parse(fs46.readFileSync(graphPath, "utf-8"));
+    if (raw && typeof raw === "object") {
+      const nodes = raw.nodes;
+      if (Array.isArray(nodes)) return nodes.length;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function listOverlays() {
+  const root = worldsRoot2();
+  if (!fs46.existsSync(root)) return [];
+  const records = [];
+  let worldDirs;
+  try {
+    worldDirs = fs46.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  for (const worldEntry of worldDirs) {
+    if (!worldEntry.isDirectory()) continue;
+    const worldId = worldEntry.name;
+    const worldDir = path48.join(root, worldId);
+    let cloneDirs;
+    try {
+      cloneDirs = fs46.readdirSync(worldDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const cloneEntry of cloneDirs) {
+      if (!cloneEntry.isDirectory()) continue;
+      const graphifyOut = path48.join(worldDir, cloneEntry.name, "graphify-out");
+      if (!fs46.existsSync(graphifyOut)) continue;
+      records.push({
+        world_id: worldId,
+        clone_dir: cloneEntry.name,
+        graphify_out_path: graphifyOut,
+        graphify_out_size_bytes: dirSizeBytes(graphifyOut),
+        node_count: readOverlayNodeCount(graphifyOut)
+      });
+    }
+  }
+  return records;
+}
+function listPristines(overlays) {
+  const root = kgRoot2();
+  if (!fs46.existsSync(root)) return [];
+  const records = [];
+  let entries;
+  try {
+    entries = fs46.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const workspace = entry.name;
+    try {
+      validateWorkspaceName(workspace);
+    } catch {
+      continue;
+    }
+    const fresh = readFreshness(workspace);
+    const graphifyOut = path48.join(kgPristinePath(workspace), "graphify-out");
+    const size = dirSizeBytes(graphifyOut);
+    const worldCount = overlays.filter((o) => o.clone_dir === workspace).length;
+    records.push({
+      workspace,
+      built_at: fresh?.built_at ?? null,
+      node_count: fresh?.node_count ?? null,
+      graphify_version: fresh?.graphify_version ?? null,
+      graphify_out_size_bytes: size,
+      world_count: worldCount
+    });
+  }
+  return records.sort((a, b) => a.workspace.localeCompare(b.workspace));
+}
+function classifyCap(totalBytes) {
+  if (totalBytes >= HARD_CAP_BYTES) return "hard-critical";
+  if (totalBytes >= SOFT_CAP_BYTES) return "soft-warn";
+  return "ok";
+}
+function buildReport(workspaceFilter) {
+  if (workspaceFilter) validateWorkspaceName(workspaceFilter);
+  const allOverlays = listOverlays();
+  const allPristines = listPristines(allOverlays);
+  const pristines = workspaceFilter ? allPristines.filter((p) => p.workspace === workspaceFilter) : allPristines;
+  const overlays = workspaceFilter ? allOverlays.filter((o) => o.clone_dir === workspaceFilter) : allOverlays;
+  const totalBytes = pristines.reduce((acc, p) => acc + p.graphify_out_size_bytes, 0) + overlays.reduce((acc, o) => acc + o.graphify_out_size_bytes, 0);
+  return {
+    pristines,
+    overlays,
+    total_bytes: totalBytes,
+    cap_status: classifyCap(totalBytes)
+  };
+}
+function renderHuman(report, workspaceFilter) {
+  const lines = [];
+  if (report.pristines.length === 0 && report.overlays.length === 0) {
+    if (workspaceFilter) {
+      lines.push(`No KG state for workspace "${workspaceFilter}".`);
+    } else {
+      lines.push("No KG state on this host yet. Run `olam kg build` from a workspace clone.");
+    }
+    return lines.join("\n");
+  }
+  if (report.pristines.length > 0) {
+    lines.push("Pristines:");
+    lines.push(
+      [
+        "workspace".padEnd(24),
+        "built_at".padEnd(22),
+        "nodes".padStart(8),
+        "size".padStart(10),
+        "worlds".padStart(7)
+      ].join("  ")
+    );
+    lines.push("-".repeat(74));
+    for (const p of report.pristines) {
+      lines.push(
+        [
+          p.workspace.padEnd(24),
+          (p.built_at ?? "\u2014").padEnd(22),
+          String(p.node_count ?? "\u2014").padStart(8),
+          formatBytes4(p.graphify_out_size_bytes).padStart(10),
+          String(p.world_count).padStart(7)
+        ].join("  ")
+      );
+    }
+    lines.push("");
+  }
+  if (report.overlays.length > 0) {
+    lines.push("Overlays:");
+    lines.push(
+      [
+        "world_id".padEnd(24),
+        "clone".padEnd(20),
+        "nodes".padStart(8),
+        "size".padStart(10)
+      ].join("  ")
+    );
+    lines.push("-".repeat(66));
+    for (const o of report.overlays) {
+      lines.push(
+        [
+          o.world_id.padEnd(24),
+          o.clone_dir.padEnd(20),
+          String(o.node_count ?? "\u2014").padStart(8),
+          formatBytes4(o.graphify_out_size_bytes).padStart(10)
+        ].join("  ")
+      );
+    }
+    lines.push("");
+  }
+  lines.push(`Total: ${formatBytes4(report.total_bytes)} (cap: ${report.cap_status})`);
+  return lines.join("\n");
+}
+async function runKgStatus(workspaceArg, opts) {
+  let report;
+  try {
+    report = buildReport(workspaceArg);
+  } catch (err) {
+    printError(err.message);
+    return {
+      exitCode: 1,
+      report: { pristines: [], overlays: [], total_bytes: 0, cap_status: "ok" }
+    };
+  }
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+  } else {
+    process.stdout.write(renderHuman(report, workspaceArg) + "\n");
+  }
+  if (report.cap_status === "soft-warn") {
+    printWarning(
+      `KG storage at ${formatBytes4(report.total_bytes)} \u2014 exceeds 1.5GB soft cap. Consider pruning stale pristines via \`rm -rf ~/.olam/kg/<workspace>\` after operator review.`
+    );
+  } else if (report.cap_status === "hard-critical") {
+    printError(
+      `KG storage at ${formatBytes4(report.total_bytes)} \u2014 exceeds 5GB hard cap. Prune stale pristines or overlays before running \`olam kg build\` again.`
+    );
+    return { exitCode: 1, report };
+  }
+  return { exitCode: 0, report };
+}
+function registerKgStatusCommand(kg) {
+  kg.command("status").description(
+    "Report pristine + overlay KG state for every workspace (or one named workspace). Emits 1.5GB soft-cap warning + 5GB hard-cap critical error on stderr."
+  ).argument("[workspace]", "workspace name (lowercase alphanumeric + hyphens/underscores)").option("--json", "emit the report as JSON instead of a compact table").action(async (workspaceArg, opts) => {
+    const r = await runKgStatus(workspaceArg, opts);
+    if (r.exitCode !== 0) process.exitCode = r.exitCode;
+  });
+}
+
+// src/commands/kg-watch.ts
+import { spawn as spawn7 } from "node:child_process";
+import fs47 from "node:fs";
+import path49 from "node:path";
+init_output();
+function pidFilePath(workspace) {
+  return path49.join(kgPristinePath(workspace), ".watch.pid");
+}
+function isPidAlive3(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = err.code;
+    if (code === "EPERM") return true;
+    return false;
+  }
+}
+function readAndClassifyPid(workspace) {
+  const file = pidFilePath(workspace);
+  if (!fs47.existsSync(file)) return { status: "no-pidfile", pid: null };
+  let pid;
+  try {
+    const raw = fs47.readFileSync(file, "utf-8").trim();
+    pid = Number.parseInt(raw, 10);
+  } catch {
+    fs47.rmSync(file, { force: true });
+    return { status: "stale-reclaimed", pid: null };
+  }
+  if (!Number.isInteger(pid) || pid <= 0) {
+    fs47.rmSync(file, { force: true });
+    return { status: "stale-reclaimed", pid: null };
+  }
+  if (isPidAlive3(pid)) return { status: "active", pid };
+  fs47.rmSync(file, { force: true });
+  return { status: "stale-reclaimed", pid: null };
+}
+function writePidFile(workspace, pid) {
+  const file = pidFilePath(workspace);
+  const dir = path49.dirname(file);
+  fs47.mkdirSync(dir, { recursive: true });
+  fs47.writeFileSync(file, String(pid), { encoding: "utf-8" });
+}
+function removePidFile(workspace) {
+  const file = pidFilePath(workspace);
+  try {
+    fs47.rmSync(file, { force: true });
+  } catch {
+  }
+}
+async function runKgWatch(workspaceArg, opts, deps = {}) {
+  const cwd = deps.cwd ?? opts.cwd ?? process.cwd();
+  const name = workspaceArg ?? path49.basename(cwd).toLowerCase();
+  try {
+    validateWorkspaceName(name);
+  } catch (err) {
+    printError(err.message);
+    return { exitCode: 1, pidWritten: false };
+  }
+  const pristinePath = kgPristinePath(name);
+  const graphPath = path49.join(pristinePath, "graphify-out", "graph.json");
+  const pidState = readAndClassifyPid(name);
+  if (pidState.status === "active") {
+    printError(
+      `olam kg watch ${name} \u2014 already running (PID ${pidState.pid}). Send SIGINT to that process to stop the existing watcher first.`
+    );
+    return { exitCode: 1, pidWritten: false };
+  }
+  if (pidState.status === "stale-reclaimed") {
+    printInfo("stale-pid", `reclaimed dead PID file at ${pidFilePath(name)}`);
+  }
+  const spawnFn = deps.spawnImpl ?? spawn7;
+  const child = spawnFn(
+    "graphify",
+    [cwd, "--watch", "--update", "--graph", graphPath],
+    {
+      cwd,
+      env: process.env,
+      detached: false,
+      stdio: "inherit"
+    }
+  );
+  if (typeof child.pid !== "number") {
+    printError("graphify failed to launch (no PID assigned)");
+    return { exitCode: 1, pidWritten: false };
+  }
+  writePidFile(name, child.pid);
+  printSuccess(`olam kg watch ${name} \u2014 graphify PID ${child.pid} (Ctrl-C to stop)`);
+  if (deps.registerSignalHandlers !== false) {
+    const forward = (sig) => {
+      if (child.pid && !child.killed) {
+        try {
+          process.kill(child.pid, sig);
+        } catch {
+        }
+      }
+    };
+    process.on("SIGINT", () => forward("SIGINT"));
+    process.on("SIGTERM", () => forward("SIGTERM"));
+  }
+  return new Promise((resolve11) => {
+    child.on("exit", (code, signal) => {
+      removePidFile(name);
+      const exitCode = typeof code === "number" ? code : signal === "SIGINT" || signal === "SIGTERM" ? 0 : 1;
+      resolve11({ exitCode, pidWritten: true });
+    });
+    child.on("error", (err) => {
+      removePidFile(name);
+      printError(`graphify subprocess error: ${err.message}`);
+      resolve11({ exitCode: 1, pidWritten: true });
+    });
+  });
+}
+function registerKgWatchCommand(kg) {
+  kg.command("watch").description(
+    "Run graphify --watch against a workspace, keeping its pristine KG fresh as host-side commits land. Single-instance via PID file; Ctrl-C cleanly stops."
+  ).argument("[workspace]", "workspace name (lowercase alphanumeric + hyphens/underscores)").action(async (workspaceArg) => {
+    const r = await runKgWatch(workspaceArg, {});
+    if (r.exitCode !== 0) process.exitCode = r.exitCode;
+  });
+}
+
+// src/commands/kg-build.ts
 var DEFAULT_DEVBOX_IMAGE2 = "olam-devbox:latest";
 function resolveWorkspace(arg) {
   const cwd = process.cwd();
-  const name = arg ?? path48.basename(cwd).toLowerCase();
+  const name = arg ?? path50.basename(cwd).toLowerCase();
   validateWorkspaceName(name);
   return { name, sourcePath: cwd };
 }
@@ -26425,10 +26824,10 @@ function copyWorkspaceToScratch(source, scratch) {
   return "cp-r";
 }
 function parseNodeCount(graphifyOutDir) {
-  const graphPath = path48.join(graphifyOutDir, "graph.json");
-  if (!fs46.existsSync(graphPath)) return null;
+  const graphPath = path50.join(graphifyOutDir, "graph.json");
+  if (!fs48.existsSync(graphPath)) return null;
   try {
-    const content = fs46.readFileSync(graphPath, "utf-8");
+    const content = fs48.readFileSync(graphPath, "utf-8");
     const data = JSON.parse(content);
     return Array.isArray(data.nodes) ? data.nodes.length : null;
   } catch {
@@ -26462,10 +26861,10 @@ async function runKgBuild(workspaceArg, options = {}) {
     return { exitCode: 2 };
   }
   const outDir = kgPristinePath(workspace.name);
-  const scratchDir = path48.join(outDir, "scratch");
-  fs46.mkdirSync(outDir, { recursive: true });
-  if (fs46.existsSync(scratchDir)) fs46.rmSync(scratchDir, { recursive: true, force: true });
-  fs46.mkdirSync(scratchDir);
+  const scratchDir = path50.join(outDir, "scratch");
+  fs48.mkdirSync(outDir, { recursive: true });
+  if (fs48.existsSync(scratchDir)) fs48.rmSync(scratchDir, { recursive: true, force: true });
+  fs48.mkdirSync(scratchDir);
   const human = !options.json;
   if (human) {
     printInfo("kg build", `workspace=${workspace.name} source=${workspace.sourcePath}`);
@@ -26493,14 +26892,14 @@ async function runKgBuild(workspaceArg, options = {}) {
       printError(`graphify update failed (exit ${r.status})`);
       return { exitCode: r.status ?? 1 };
     }
-    const scratchOut = path48.join(scratchDir, "graphify-out");
-    const finalOut = path48.join(outDir, "graphify-out");
-    if (!fs46.existsSync(scratchOut)) {
+    const scratchOut = path50.join(scratchDir, "graphify-out");
+    const finalOut = path50.join(outDir, "graphify-out");
+    if (!fs48.existsSync(scratchOut)) {
       printError(`graphify produced no graphify-out/ in scratch (${scratchOut})`);
       return { exitCode: 1 };
     }
-    if (fs46.existsSync(finalOut)) fs46.rmSync(finalOut, { recursive: true, force: true });
-    fs46.renameSync(scratchOut, finalOut);
+    if (fs48.existsSync(finalOut)) fs48.rmSync(finalOut, { recursive: true, force: true });
+    fs48.renameSync(scratchOut, finalOut);
     const durationMs = Date.now() - started;
     const nodeCount = parseNodeCount(finalOut);
     const version = readGraphifyVersion(image);
@@ -26512,8 +26911,8 @@ async function runKgBuild(workspaceArg, options = {}) {
       workspace: workspace.name,
       scratch_strategy: scratchStrategy
     };
-    fs46.writeFileSync(
-      path48.join(outDir, "freshness.json"),
+    fs48.writeFileSync(
+      path50.join(outDir, "freshness.json"),
       JSON.stringify(freshness, null, 2) + "\n",
       "utf-8"
     );
@@ -26527,8 +26926,8 @@ async function runKgBuild(workspaceArg, options = {}) {
     }
     return { exitCode: 0, freshness, outputDir: finalOut };
   } finally {
-    if (fs46.existsSync(scratchDir)) {
-      fs46.rmSync(scratchDir, { recursive: true, force: true });
+    if (fs48.existsSync(scratchDir)) {
+      fs48.rmSync(scratchDir, { recursive: true, force: true });
     }
   }
 }
@@ -26540,21 +26939,23 @@ function registerKg(program2) {
     const r = await runKgBuild(workspaceArg, opts);
     if (r.exitCode !== 0) process.exitCode = r.exitCode;
   });
+  registerKgStatusCommand(kg);
+  registerKgWatchCommand(kg);
 }
 
 // src/pleri-config.ts
-import * as fs47 from "node:fs";
-import * as path49 from "node:path";
+import * as fs49 from "node:fs";
+import * as path51 from "node:path";
 function isPleriConfigured(configDir = process.env.OLAM_CONFIG_DIR ?? ".olam") {
   if (process.env.PLERI_BASE_URL) {
     return true;
   }
-  const configPath = path49.join(configDir, "config.yaml");
-  if (!fs47.existsSync(configPath)) {
+  const configPath = path51.join(configDir, "config.yaml");
+  if (!fs49.existsSync(configPath)) {
     return false;
   }
   try {
-    const contents = fs47.readFileSync(configPath, "utf8");
+    const contents = fs49.readFileSync(configPath, "utf8");
     return /^[^#\n]*\bpleri:/m.test(contents);
   } catch {
     return false;