@kal-elsam/kairo-runtime 0.7.0 → 0.9.0

package/README.md

@@ -35,23 +35,43 @@ kairo
 **First run** (no `~/.harness/state.json`): interactive onboarding → safe diagnosis →
 setup with confirmation → full-screen operations cockpit.
 
-**Later runs** (state present): full-screen Control Center that explains what Kairo
-does, shows coverage/integrity, evidence-backed proposals, and the next governance
-action (scan → evidence → preview → confirm → apply → re-scan → recovery). Runs stay
-secondary. Layout adapts to terminal size:
+**Later runs** (state present): full-screen Control Center oriented around user
+tasks — overall health, one next action, activity, pending alerts, and guided
+governance (scan → evidence → preview → confirm → apply → re-scan → recovery).
+Runs stay secondary. Layout adapts to terminal size:
 
 | Mode | Size | Layout |
 |------|------|--------|
-| Wide | ≥100 cols × ≥28 rows | Nav + Home/content + system |
-| Compact | ≥72×20 | Nav + Home/content (readiness embedded) |
-| Minimal | 60–71 cols or short height | Selected section + essential readiness/next/recent |
+| Wide | ≥100 cols × ≥28 rows | TopBar + nav strip + main panel + footer |
+| Compact | ≥72×20 | Same single-panel shell (tighter lists) |
+| Minimal | 60–71 cols or short height | Selected section + essential readiness/next |
 | Below gate | <60 cols | Explicit TTY fallback (Ink disabled) |
 
-Keys: `↑↓` navigate (selection explanation updates) · `Enter` open ·
-`Esc` back (exit only from Home) · `R` refresh/retry · `C` cancel run · `?` help.
-`Tab` switches region only when content is interactive (run lists / New run).
+Keys: `↑↓` navigate · `Enter` open/activate · `/` actions palette ·
+`Esc` back (exit only from Overview) · `R` refresh/retry · `C` cancel run ·
+`?` help. `Tab` switches region when content is interactive (runs, alerts,
+Activity, Settings, launch).
 
-Navigation labels: Home · Running now · History · Agents · New run · System health.
+Navigation: Overview · Governance · Activity · Orchestration · Usage · Settings.
+
+### Monitor (opt-in)
+
+```bash
+kairo monitor enable
+kairo monitor status
+kairo monitor tick
+kairo monitor disable
+```
+
+Scans governance drift and orphan/failed runs into the alert store. On macOS,
+`enable` can install a LaunchAgent; other OS degrade honestly. Notifications fire
+only when a new alert claim succeeds.
+
+### Settings (curated integrations)
+
+Settings browses a curated catalog (pinned `pi-usage-widget@0.2.1`, MIT).
+Preview → confirm shows an in-session confirmation receipt (`wroteFiles: false`);
+it does not persist or install anything.
 
 Respects `NO_COLOR`, `HARNESS_ASCII=1`, and `HARNESS_INK=0`. Status is always labeled
 in text, never color alone.
@@ -301,6 +321,18 @@ Launches `pi --mode json --no-session` (optional `--model`). `read-only` maps to
 to `--approve`). Custom `PI_CODING_AGENT_DIR` blocks config writes in 0.6.0 but does
 not block runtime. Kairo does not install Pi or assert subscription/entitlement.
 
+### Orchestrated Pi (Context Orchestration)
+
+```bash
+kairo run --agent pi --strategy orchestrated --task "..."
+```
+
+Loads the managed minion extension, injects `KAIRO_ORCH_*`, and persists a depth≤1
+DAG under `~/.harness/runs/<rootRunId>/orchestration/state.json`. Normal completion
+seals write-once `receipt.json`; interrupt recovery seals `recovered:true`. Limits:
+concurrency 2, max attempts 2, context compact at 70% / stop at 90%, cascade cancel
+on parent abort. No same-root resume. Direct `--strategy direct` (default) is unchanged.
+
 ### Bounded review (Codex / Pi)
 
 Read-only native review against a Git snapshot. Never mutates the repo, never

package/global-template/components/catalog.json

@@ -13,7 +13,10 @@
         { "id": "assets", "type": "assets" },
         { "id": "drift", "type": "drift" }
       ],
-      "assetFiles": ["orchestrator.md"],
+      "assetFiles": [
+        "orchestrator.md",
+        "extensions/pi/kairo-minion.js"
+      ],
       "adapterHints": {}
     },
     {

package/global-template/components/orchestrator/extensions/pi/kairo-minion.js

@@ -0,0 +1,604 @@
+/**
+ * Kairo Pi extension under ~/.harness (explicit --extension load only).
+ * Parent: kairo_delegate + cascade cancel. Child: path + budget guards.
+ */
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, realpath, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
+
+export const MINION_CONCURRENCY = 2;
+export const MINION_ABORT_GRACE_MS = 5_000;
+export const MINION_TOOLS = "read,grep,find,ls";
+export const MAX_TASK_ATTEMPTS = 2;
+export const BUDGET_COMPACT_RATIO = 0.7;
+export const BUDGET_STOP_RATIO = 0.9;
+export const PATH_DENIED = "KAIRO_PATH_DENIED";
+export const BUDGET_EXCEEDED = "budget_exceeded";
+export const GUARDED_TOOLS = new Set(["read", "grep", "find", "ls"]);
+export const GENERIC_MINION_TASK =
+  "Read brief JSON at KAIRO_MINION_BRIEF. Return JSON only: "
+  + "{\"taskId\",\"summary\",\"decisions\",\"files\",\"risks\",\"evidence\",\"usage\",\"compact\"}.";
+
+export function resolveSelfExtensionPath() {
+  return fileURLToPath(import.meta.url);
+}
+
+export function isChildMinionMode(env = process.env) {
+  return typeof env.KAIRO_MINION_BRIEF === "string" && env.KAIRO_MINION_BRIEF.trim() !== "";
+}
+
+export function minionStatusPath(briefPath) {
+  return `${briefPath}.status.json`;
+}
+
+/** Cancelable concurrency: cancel rejects queued work and blocks new runs. */
+export function createConcurrencyGate(limit = MINION_CONCURRENCY) {
+  let inFlight = 0;
+  const queue = [];
+  let cancelled = false;
+  const abortErr = () => Object.assign(new Error("Minion cancelled."), { code: "aborted" });
+  return {
+    get cancelled() { return cancelled; },
+    get active() { return inFlight; },
+    get queued() { return queue.length; },
+    cancel() {
+      cancelled = true;
+      while (queue.length) queue.shift().reject(abortErr());
+    },
+    async run(fn) {
+      if (cancelled) throw abortErr();
+      if (inFlight >= limit) {
+        await new Promise((resolve, reject) => queue.push({ resolve, reject }));
+        if (cancelled) throw abortErr();
+      }
+      inFlight += 1;
+      try { return await fn(); }
+      finally {
+        inFlight -= 1;
+        queue.shift()?.resolve();
+      }
+    }
+  };
+}
+
+export function createProcessRegistry({ abortGraceMs = MINION_ABORT_GRACE_MS } = {}) {
+  const active = new Set();
+  let cancelled = false;
+  return {
+    get cancelled() { return cancelled; },
+    get size() { return active.size; },
+    track(child) {
+      if (cancelled) {
+        safeKill(child, "SIGTERM");
+        return false;
+      }
+      active.add(child);
+      child.on?.("close", () => active.delete(child));
+      return true;
+    },
+    async cancelAll() {
+      cancelled = true;
+      for (const child of [...active]) safeKill(child, "SIGTERM");
+      if (abortGraceMs > 0) await new Promise((r) => setTimeout(r, abortGraceMs));
+      for (const child of [...active]) safeKill(child, "SIGKILL");
+    }
+  };
+}
+
+const defaultGate = createConcurrencyGate();
+const defaultRegistry = createProcessRegistry();
+
+export function buildMinionArgs({ extensionPath = resolveSelfExtensionPath() } = {}) {
+  return [
+    "--mode", "json", "-p", "--no-session",
+    "--tools", MINION_TOOLS,
+    "--no-extensions", "--extension", extensionPath,
+    "--no-skills", "--no-prompt-templates", "--no-context-files", "--no-approve",
+    GENERIC_MINION_TASK
+  ];
+}
+
+function hasDotDot(path) {
+  return /(^|[\\/])\.\.([\\/]|$)/.test(String(path ?? ""));
+}
+
+export function extractToolPaths(input) {
+  if (!input || typeof input !== "object") return [];
+  const out = [];
+  for (const key of ["path", "file", "target", "directory", "dir", "root"]) {
+    if (typeof input[key] === "string" && input[key].trim()) out.push(input[key]);
+  }
+  for (const key of ["paths", "files"]) {
+    if (!Array.isArray(input[key])) continue;
+    for (const entry of input[key]) {
+      if (typeof entry === "string" && entry.trim()) out.push(entry);
+    }
+  }
+  return out;
+}
+
+export async function resolveAdmittedRoots(admittedPaths, cwd) {
+  if (!Array.isArray(admittedPaths) || admittedPaths.length === 0) return null;
+  const roots = [];
+  for (const raw of admittedPaths) {
+    if (typeof raw !== "string" || !raw.trim() || hasDotDot(raw)) return null;
+    const abs = isAbsolute(raw) ? raw : resolve(cwd, raw);
+    try { roots.push(await realpath(abs)); }
+    catch { return null; }
+  }
+  return roots.length ? roots : null;
+}
+
+export async function isPathAdmitted(targetPath, roots, cwd) {
+  if (!Array.isArray(roots) || roots.length === 0) return false;
+  if (typeof targetPath !== "string" || !targetPath.trim() || hasDotDot(targetPath)) return false;
+  const abs = isAbsolute(targetPath) ? targetPath : resolve(cwd, targetPath);
+  let real;
+  try { real = await realpath(abs); }
+  catch { return false; }
+  for (const root of roots) {
+    if (real === root) return true;
+    const prefix = root.endsWith(sep) ? root : `${root}${sep}`;
+    if (real.startsWith(prefix)) return true;
+  }
+  return false;
+}
+
+export async function evaluateToolPathAccess({
+  toolName, input, admittedPaths, cwd = process.cwd()
+}) {
+  if (!GUARDED_TOOLS.has(toolName)) return { allow: true };
+  const roots = await resolveAdmittedRoots(admittedPaths, cwd);
+  if (!roots) return { allow: false, reason: PATH_DENIED };
+  const paths = extractToolPaths(input);
+  const targets = paths.length ? paths : [cwd];
+  for (const target of targets) {
+    if (!(await isPathAdmitted(target, roots, cwd))) {
+      return { allow: false, reason: PATH_DENIED };
+    }
+  }
+  return { allow: true };
+}
+
+/** Ratio from percent (0–100) or tokens/contextWindow. */
+export function contextUsageRatio(usage) {
+  if (!usage || typeof usage !== "object") return 0;
+  if (Number.isFinite(usage.percent)) return Math.max(0, usage.percent) / 100;
+  const tokens = Number(usage.tokens ?? usage.contextTokens ?? 0);
+  const limit = Number(usage.contextWindow ?? usage.contextLimit ?? 0);
+  return limit > 0 ? Math.max(0, tokens) / limit : 0;
+}
+
+export function evaluateContextBudget(usage, {
+  compactRatio = BUDGET_COMPACT_RATIO, stopRatio = BUDGET_STOP_RATIO
+} = {}) {
+  const ratio = contextUsageRatio(usage);
+  if (ratio >= stopRatio) return { ratio, action: "stop" };
+  if (ratio >= compactRatio) return { ratio, action: "compact" };
+  return { ratio, action: "continue" };
+}
+
+export function createBudgetAttemptState() {
+  return { compactedThisAttempt: false, compactObserved: false, stopReason: null };
+}
+
+async function writeMinionStatus(statusPath, payload) {
+  if (!statusPath) return;
+  await writeFile(statusPath, JSON.stringify(payload), { mode: 0o600 });
+}
+
+/** Child: after each turn, compact once in [70,90) or abort at ≥90%. */
+export function registerBudgetGuard(pi, {
+  statusPath = null,
+  state = createBudgetAttemptState(),
+  compactRatio = BUDGET_COMPACT_RATIO,
+  stopRatio = BUDGET_STOP_RATIO
+} = {}) {
+  const persist = async () => {
+    if (!state.stopReason && !state.compactObserved) return;
+    await writeMinionStatus(statusPath, {
+      code: state.stopReason, compact: state.compactObserved
+    });
+  };
+
+  pi.on("compaction_end", async () => {
+    state.compactObserved = true;
+    await persist();
+  });
+
+  pi.on("turn_end", async (_event, ctx) => {
+    if (state.stopReason) return;
+    const usage = typeof ctx?.getContextUsage === "function" ? ctx.getContextUsage() : null;
+    const { action } = evaluateContextBudget(usage, { compactRatio, stopRatio });
+    if (action === "continue") return;
+    if (action === "compact") {
+      if (state.compactedThisAttempt) return;
+      state.compactedThisAttempt = true;
+      if (typeof ctx?.compact === "function") {
+        ctx.compact({
+          onComplete: async () => {
+            state.compactObserved = true;
+            await persist();
+          },
+          onError: () => {}
+        });
+      }
+      return;
+    }
+    state.stopReason = BUDGET_EXCEEDED;
+    await persist();
+    if (typeof ctx?.abort === "function") ctx.abort();
+  });
+
+  return state;
+}
+
+export function registerPathGuard(pi, {
+  briefPath = process.env.KAIRO_MINION_BRIEF,
+  cwd = process.cwd(),
+  loadBrief = async (path) => JSON.parse(await readFile(path, "utf8"))
+} = {}) {
+  let admittedPromise = null;
+  const loadAdmitted = () => {
+    if (!admittedPromise) {
+      admittedPromise = (async () => {
+        if (typeof briefPath !== "string" || !briefPath.trim()) return [];
+        try {
+          const brief = await loadBrief(briefPath);
+          return Array.isArray(brief?.admittedPaths) ? brief.admittedPaths : [];
+        } catch {
+          return [];
+        }
+      })();
+    }
+    return admittedPromise;
+  };
+
+  pi.on("tool_call", async (event) => {
+    const toolName = event?.toolName ?? event?.name;
+    if (!GUARDED_TOOLS.has(toolName)) return;
+    const admittedPaths = await loadAdmitted();
+    const verdict = await evaluateToolPathAccess({
+      toolName, input: event?.input ?? {}, admittedPaths, cwd
+    });
+    if (!verdict.allow) return { block: true, reason: PATH_DENIED };
+  });
+}
+
+function assistantText(message) {
+  if (!Array.isArray(message?.content)) return null;
+  const text = message.content
+    .filter((b) => b?.type === "text" && typeof b.text === "string")
+    .map((b) => b.text).join("");
+  return text.trim() === "" ? null : text;
+}
+
+function normalizeUsage(usage, acc = {}) {
+  if (!usage || typeof usage !== "object") return acc;
+  const add = (key, ...alts) => {
+    for (const a of alts) {
+      if (Number.isFinite(usage[a])) { acc[key] = (acc[key] ?? 0) + usage[a]; return; }
+    }
+  };
+  add("inputTokens", "input", "inputTokens", "input_tokens");
+  add("outputTokens", "output", "outputTokens", "output_tokens");
+  if (Number.isFinite(usage.totalTokens)) acc.totalTokens = (acc.totalTokens ?? 0) + usage.totalTokens;
+  else if (Number.isFinite(usage.total)) acc.totalTokens = (acc.totalTokens ?? 0) + usage.total;
+  const cost = typeof usage.cost === "number" ? usage.cost
+    : typeof usage.cost?.total === "number" ? usage.cost.total : null;
+  if (cost != null) acc.cost = (acc.cost ?? 0) + cost;
+  return acc;
+}
+
+function failHandoff(message, code = "invalid_handoff") {
+  const err = new Error(message);
+  err.code = code;
+  throw err;
+}
+
+export function parseMinionNdjson(stdout) {
+  let lastText = null;
+  let usage = {};
+  let streamError = null;
+  for (const line of String(stdout ?? "").split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let parsed;
+    try { parsed = JSON.parse(trimmed); } catch { continue; }
+    if (parsed?.type === "error") {
+      streamError = "Minion stream error.";
+      continue;
+    }
+    if (parsed?.type === "message_end" && parsed.message?.role === "assistant") {
+      const stop = parsed.message.stopReason;
+      if (stop === "error" || stop === "aborted") {
+        streamError = `Minion stopReason ${stop}.`;
+      } else {
+        const text = assistantText(parsed.message);
+        if (text) lastText = text;
+      }
+    }
+    if (parsed?.type === "turn_end" && parsed.usage) usage = normalizeUsage(parsed.usage, usage);
+  }
+  if (streamError) failHandoff(streamError);
+  return { text: lastText, usage: Object.keys(usage).length ? usage : null };
+}
+
+export function parseMinionResultJson(text, { taskId }) {
+  if (typeof text !== "string" || !text.trim()) failHandoff("Minion returned no assistant message.");
+  let parsed;
+  try {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    parsed = JSON.parse(start >= 0 && end > start ? text.slice(start, end + 1) : text);
+  } catch {
+    failHandoff("Minion returned invalid JSON handoff.");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    failHandoff("Minion handoff must be an object.");
+  }
+  if (parsed.taskId && parsed.taskId !== taskId) failHandoff("Minion handoff taskId mismatch.");
+  if (typeof parsed.summary !== "string" || !parsed.summary.trim()) {
+    failHandoff("Minion handoff requires summary.");
+  }
+  for (const key of ["prompt", "stdout", "stderr", "transcript", "conversation", "toolArgs"]) {
+    if (key in parsed) failHandoff(`Minion handoff forbids field "${key}".`);
+  }
+  return {
+    taskId,
+    summary: parsed.summary.trim(),
+    decisions: (parsed.decisions ?? []).map(String),
+    files: (parsed.files ?? []).map(String),
+    risks: (parsed.risks ?? []).map(String),
+    evidence: (parsed.evidence ?? []).map(String),
+    usage: {
+      inputTokens: parsed.usage?.inputTokens ?? null,
+      outputTokens: parsed.usage?.outputTokens ?? null,
+      totalTokens: parsed.usage?.totalTokens ?? null,
+      cost: parsed.usage?.cost ?? null
+    },
+    compact: Boolean(parsed.compact)
+  };
+}
+
+function safeKill(child, signal) {
+  try { if (child.exitCode == null && child.signalCode == null) child.kill(signal); } catch { /* ignore */ }
+}
+
+async function readMinionStatus(statusPath) {
+  try {
+    return JSON.parse(await readFile(statusPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function spawnMinionProcess({
+  brief, cwd, env = process.env, signal = null, spawnImpl = spawn,
+  abortGraceMs = MINION_ABORT_GRACE_MS, gate = defaultGate,
+  registry = defaultRegistry, extensionPath = resolveSelfExtensionPath(),
+  readStatus = readMinionStatus
+} = {}) {
+  return gate.run(async () => {
+    if (registry.cancelled || gate.cancelled || signal?.aborted) {
+      failHandoff("Minion cancelled.", "aborted");
+    }
+    const dir = await mkdtemp(join(tmpdir(), "kairo-minion-"));
+    const briefPath = join(dir, "brief.json");
+    const statusPath = minionStatusPath(briefPath);
+    let child = null;
+    let abortListener = null;
+    let killTimer = null;
+    try {
+      await writeFile(briefPath, JSON.stringify(brief), { mode: 0o600 });
+      child = spawnImpl("pi", buildMinionArgs({ extensionPath }), {
+        cwd, env: { ...env, KAIRO_MINION_BRIEF: briefPath },
+        shell: false, stdio: ["ignore", "pipe", "pipe"]
+      });
+      if (!registry.track(child)) failHandoff("Minion cancelled.", "aborted");
+      let stdout = "";
+      child.stdout?.on("data", (c) => { stdout += c; });
+      child.stderr?.on("data", () => {});
+      const closed = new Promise((resolveClose, reject) => {
+        child.on("error", (error) => {
+          const err = new Error(`Minion spawn failed: ${error.message}`);
+          err.code = "invalid_handoff";
+          reject(err);
+        });
+        child.on("close", (status, sig) => resolveClose({ status, signal: sig, stdout }));
+      });
+      if (signal) {
+        const onAbort = () => {
+          safeKill(child, "SIGTERM");
+          killTimer = setTimeout(() => safeKill(child, "SIGKILL"), abortGraceMs);
+        };
+        if (signal.aborted) onAbort();
+        else {
+          abortListener = onAbort;
+          signal.addEventListener("abort", onAbort, { once: true });
+        }
+      }
+      const result = await closed;
+      const status = await readStatus(statusPath);
+      if (status?.code === BUDGET_EXCEEDED) {
+        const err = new Error("Context budget exceeded.");
+        err.code = BUDGET_EXCEEDED;
+        err.compact = Boolean(status.compact);
+        throw err;
+      }
+      if (signal?.aborted || result.signal || registry.cancelled) {
+        failHandoff("Minion aborted.", "aborted");
+      }
+      if (result.status !== 0) failHandoff(`Minion exited with status ${result.status}.`);
+      const parsed = parseMinionNdjson(result.stdout);
+      const handoff = parseMinionResultJson(parsed.text, { taskId: brief.taskId });
+      if (status?.compact) handoff.compact = true;
+      if (parsed.usage) {
+        handoff.usage = {
+          inputTokens: handoff.usage.inputTokens ?? parsed.usage.inputTokens ?? null,
+          outputTokens: handoff.usage.outputTokens ?? parsed.usage.outputTokens ?? null,
+          totalTokens: handoff.usage.totalTokens ?? parsed.usage.totalTokens ?? null,
+          cost: handoff.usage.cost ?? parsed.usage.cost ?? null
+        };
+      }
+      return handoff;
+    } finally {
+      if (abortListener && signal) signal.removeEventListener("abort", abortListener);
+      if (killTimer) clearTimeout(killTimer);
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+}
+
+/** Retry transient failures only; never cancel or budget_exceeded. */
+export async function runMinionWithRetries(opts, {
+  maxAttempts = MAX_TASK_ATTEMPTS, onAttempt = null
+} = {}) {
+  let lastError = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      if (onAttempt) await onAttempt(attempt);
+      return await spawnMinionProcess(opts);
+    } catch (error) {
+      lastError = error;
+      if (error?.code === BUDGET_EXCEEDED || error?.code === "aborted") throw error;
+      if (opts.signal?.aborted) failHandoff("Minion aborted.", "aborted");
+      if (attempt >= maxAttempts) throw error;
+    }
+  }
+  throw lastError;
+}
+
+const ORCH_ENV = Object.freeze({
+  HOME: "KAIRO_ORCH_HOME",
+  ROOT_RUN_ID: "KAIRO_ORCH_ROOT_RUN_ID",
+  ROOT_TASK_ID: "KAIRO_ORCH_ROOT_TASK_ID",
+  MODULE: "KAIRO_ORCH_MODULE"
+});
+
+export async function resolveOrchPersist(env = process.env) {
+  const homeDir = env[ORCH_ENV.HOME];
+  const rootRunId = env[ORCH_ENV.ROOT_RUN_ID];
+  const rootTaskId = env[ORCH_ENV.ROOT_TASK_ID];
+  const modulePath = env[ORCH_ENV.MODULE];
+  if (![homeDir, rootRunId, rootTaskId, modulePath].every((v) => typeof v === "string" && v.trim())) {
+    return null;
+  }
+  const api = await import(pathToFileURL(modulePath).href);
+  return { homeDir, rootRunId, rootTaskId, api };
+}
+
+function registerDelegate(pi, {
+  gate = createConcurrencyGate(),
+  registry = createProcessRegistry(),
+  env = process.env,
+  spawnImpl = spawn,
+  readStatus = null
+} = {}) {
+  const cascade = async () => {
+    gate.cancel();
+    await registry.cancelAll();
+  };
+  pi.on("session_shutdown", cascade);
+
+  pi.registerTool({
+    name: "kairo_delegate",
+    label: "Kairo Delegate",
+    description: "Delegate a bounded read-only subtask to an ephemeral Pi minion.",
+    parameters: {
+      type: "object",
+      properties: {
+        taskId: { type: "string" },
+        parentTaskId: { type: "string" },
+        objective: { type: "string" },
+        constraints: { type: "array", items: { type: "string" } },
+        admittedPaths: { type: "array", items: { type: "string" } },
+        exitCriteria: { type: "array", items: { type: "string" } }
+      },
+      required: ["taskId", "parentTaskId", "objective"]
+    },
+    async execute(_id, params, signal) {
+      if (signal) {
+        const onAbort = () => { void cascade(); };
+        if (signal.aborted) onAbort();
+        else signal.addEventListener("abort", onAbort, { once: true });
+      }
+      const orch = await resolveOrchPersist(env);
+      const parentTaskId = params.parentTaskId;
+      const taskId = params.taskId;
+      if (orch && (taskId === orch.rootTaskId || parentTaskId !== orch.rootTaskId)) {
+        throw Object.assign(new Error("Delegate lineage must honor KAIRO_ORCH_ROOT_TASK_ID."), { code: "invalid_lineage" });
+      }
+      let lastAttempt = 0;
+      const patch = orch
+        ? (fields) => orch.api.applyMinionDagUpdate(orch.rootRunId, {
+          homeDir: orch.homeDir, taskId, parentTaskId, ...fields
+        })
+        : null;
+      const objectiveDigest = orch
+        ? orch.api.digestAllowlisted({ objective: params.objective })
+        : null;
+      try {
+        if (patch) {
+          await patch({
+            state: orch.api.DAG_NODE_STATES.PENDING, attempt: 0, objectiveDigest
+          });
+        }
+        const handoff = await runMinionWithRetries({
+          brief: {
+            taskId, parentTaskId, objective: params.objective,
+            constraints: params.constraints ?? [],
+            admittedPaths: params.admittedPaths ?? [],
+            exitCriteria: params.exitCriteria ?? []
+          },
+          cwd: process.cwd(),
+          signal, gate, registry, env, spawnImpl,
+          ...(readStatus ? { readStatus } : {})
+        }, {
+          onAttempt: patch
+            ? async (attempt) => {
+              lastAttempt = attempt;
+              await patch({
+                state: orch.api.DAG_NODE_STATES.RUNNING, attempt, objectiveDigest
+              });
+            }
+            : null
+        });
+        if (patch) {
+          await patch({
+            state: orch.api.DAG_NODE_STATES.COMPLETED, attempt: lastAttempt || 1,
+            objectiveDigest, result: handoff
+          });
+        }
+        return handoff;
+      } catch (error) {
+        if (patch) {
+          const code = error?.code === BUDGET_EXCEEDED
+            ? BUDGET_EXCEEDED
+            : error?.code === "aborted" ? "aborted" : (error?.code ?? "invalid_handoff");
+          const state = code === "aborted"
+            ? orch.api.DAG_NODE_STATES.CANCELLED
+            : orch.api.DAG_NODE_STATES.FAILED;
+          await patch({
+            state, attempt: lastAttempt || 1, objectiveDigest, error: { code }
+          });
+        }
+        throw error;
+      }
+    }
+  });
+  return { gate, registry, cascade };
+}
+
+export default function registerKairoMinion(pi, env = process.env, opts = {}) {
+  if (isChildMinionMode(env)) {
+    const briefPath = env.KAIRO_MINION_BRIEF;
+    registerPathGuard(pi, { briefPath });
+    registerBudgetGuard(pi, { statusPath: minionStatusPath(briefPath) });
+    return { mode: "child" };
+  }
+  registerDelegate(pi, { env, ...opts });
+  return { mode: "parent" };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Pi, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",