@kal-elsam/kairo-runtime 0.5.0 → 0.6.0

package/README.md

@@ -261,7 +261,7 @@ node ./bin/kairo.js install --dry-run
 
 ## Supported adapters (agent-global)
 
-Kairo Runtime does **not** install Cursor, Codex, OpenCode, or Claude Code. It detects
+Kairo Runtime does **not** install Cursor, Codex, OpenCode, Claude Code, or Pi. It detects
 their home-directory roots and writes managed sections into their config files.
 
 | Adapter | Label | Root | Config file |
@@ -270,6 +270,7 @@ their home-directory roots and writes managed sections into their config files.
 | `codex` | Codex | `~/.codex` | `~/.codex/AGENTS.md` |
 | `opencode` | OpenCode | `~/.config/opencode` | `~/.config/opencode/AGENTS.md` |
 | `claude` | Claude Code | `~/.claude` | `~/.claude/CLAUDE.md` |
+| `pi` | Pi | `~/.pi/agent` | `~/.pi/agent/AGENTS.md` |
 
 Inspect detection and managed state:
 
@@ -281,14 +282,25 @@ kairo adapters --json
 Agent selection defaults:
 
 - If agent roots are detected → configure detected agents only.
-- If none are detected → safe fallback to all four supported adapters.
-- Force all four explicitly:
+- If none are detected → safe fallback to all five supported adapters.
+- Force all five explicitly:
 
 ```bash
 kairo setup --agents all
 kairo install --agents all
 ```
 
+### Pi runtime (auditable)
+
+```bash
+kairo run --agent pi --task "Review this repository" --permissions read-only --follow
+```
+
+Launches `pi --mode json --no-session` (optional `--model`). `read-only` maps to
+`--tools read,grep,find,ls`; other permission aliases are rejected (never translated
+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.
+
 Primary governance flow:
 
 ```txt
@@ -518,9 +530,11 @@ kairo components rollback engram-memory --receipt <id> --dry-run
 
 Without `--agents`, Kairo uses the intersection of detected agents and
 Kairo-managed Engram agents (`cursor`, `codex`, `opencode`, `claude` → setup slug
-`claude-code`). After setup, status is `restart_required` — restart the agent to
+`claude-code`, `pi` → `pi`). After setup, status is `restart_required` — restart the agent to
 load MCP; configuration evidence is not runtime-active. Receipts live under
-`~/.harness/integrations/engram/`.
+`~/.harness/integrations/engram/`. For Pi, positive evidence requires
+`~/.pi/agent/settings.json` packages (`npm:gentle-engram`, `npm:pi-mcp-adapter`) and
+`~/.pi/agent/mcp.json` with `mcpServers.engram`.
 
 ### SDD Core skills
 
@@ -537,7 +551,7 @@ same `sdd-core` apply path. Lifecycle keeps persona frozen (`preservePersona`):
 it never auto-activates teaching. Explicit persona changes stay on
 `kairo components configure sdd-core`.
 
-**Destinations.** Cursor, Codex, and OpenCode share `~/.agents/skills/<id>/`.
+**Destinations.** Cursor, Codex, OpenCode, and Pi share `~/.agents/skills/<id>/`.
 Claude uses `~/.claude/skills/<id>/`. One physical tree per root; consumers are
 recorded per destination.
 

package/global-template/components/catalog.json

@@ -58,7 +58,8 @@
         "cursor": "- In repos with workspace harness: also read `.cursor/rules/` and `docs/specs/`.",
         "codex": "- In repos with workspace harness: also read `.codex/skills/sdd/` when present.",
         "claude": "- In repos with workspace harness: repo `AGENTS.md` wins over `CLAUDE.md` pointers.",
-        "opencode": "- In repos with workspace harness: also read `.opencode/` SDD assets when present."
+        "opencode": "- In repos with workspace harness: also read `.opencode/` SDD assets when present.",
+        "pi": "- Skills load from `~/.agents/skills` (shared Agent Skills root). Teaching persona activates only via the managed section of `~/.pi/agent/AGENTS.md`."
       }
     },
     {
@@ -80,7 +81,8 @@
         "cursor": "- Configure Engram via `kairo components configure engram-memory` (official `engram setup cursor`).",
         "codex": "- Configure Engram via `kairo components configure engram-memory` (official `engram setup codex`).",
         "claude": "- Configure Engram via `kairo components configure engram-memory` (official `engram setup claude-code`).",
-        "opencode": "- Configure Engram via `kairo components configure engram-memory` (official `engram setup opencode`)."
+        "opencode": "- Configure Engram via `kairo components configure engram-memory` (official `engram setup opencode`).",
+        "pi": "- Configure Engram via `kairo components configure engram-memory` (official `engram setup pi`). Evidence: `~/.pi/agent/settings.json` packages + `mcp.json` engram server. Restart Pi after setup; Kairo never runs `engram doctor`/`serve` or touches `engram.db`."
       }
     },
     {

package/global-template/components/orchestrator/orchestrator.md

@@ -5,7 +5,7 @@
 ## Role
 
 The Harness Orchestrator (conductor) coordinates work across local coding agents
-(Cursor, Codex, OpenCode, Claude). It does not replace any agent. It defines how
+(Cursor, Codex, OpenCode, Claude, Pi). It does not replace any agent. It defines how
 agents hand off work and which source of truth governs.
 
 ## Authority order

package/global-template/core/orchestrator.md

@@ -5,7 +5,7 @@
 ## Role
 
 The Harness Orchestrator (conductor) coordinates work across local coding agents
-(Cursor, Codex, OpenCode, Claude). It does not replace any agent. It defines how
+(Cursor, Codex, OpenCode, Claude, Pi). It does not replace any agent. It defines how
 agents hand off work and which source of truth governs.
 
 ## Authority order

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.5.0",
-  "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Gemini, Copilot, Engram, and Graphify.",
+  "version": "0.6.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",
   "repository": {
@@ -45,6 +45,7 @@
     "agents",
     "codex",
     "cursor",
+    "pi",
     "kairo",
     "kairo-runtime",
     "harness",

package/scripts/cockpit-smoke.mjs

@@ -26,7 +26,7 @@ const root = join(dirname(fileURLToPath(import.meta.url)), "..");
 const require = createRequire(import.meta.url);
 const pkg = require(join(root, "package.json"));
 
-assert.equal(pkg.version, "0.5.0");
+assert.equal(pkg.version, "0.6.0");
 assert.ok(pkg.dependencies["ansi-escapes"]);
 
 assert.equal(resolveLayoutMode({ columns: 120, rows: 40 }), LAYOUT_MODES.WIDE);

package/scripts/install.sh

@@ -4,7 +4,7 @@
 # Safe by design:
 #   - no sudo
 #   - no shell profile changes
-#   - does not install Cursor/Codex/OpenCode/Claude
+#   - does not install Cursor/Codex/OpenCode/Claude/Pi
 #   - default ends with setup --dry-run (no writes)
 #   - explicit apply: pass --yes to run setup --yes
 #

package/scripts/installer-smoke-test.sh

@@ -88,9 +88,9 @@ if (!payload.ok || payload.overall !== 'ok') {
   process.exit(1);
 }
 const managed = payload.agents.filter((agent) => agent.managed).map((agent) => agent.id).sort();
-const expected = ['claude', 'codex', 'cursor', 'opencode'];
+const expected = ['claude', 'codex', 'cursor', 'opencode', 'pi'];
 if (JSON.stringify(managed) !== JSON.stringify(expected)) {
-  console.error('Expected all four agents managed');
+  console.error('Expected all five agents managed');
   process.exit(1);
 }
 " "$status_json"
@@ -105,7 +105,8 @@ const targets = [
   '.cursor/AGENTS.md',
   '.codex/AGENTS.md',
   '.config/opencode/AGENTS.md',
-  '.claude/CLAUDE.md'
+  '.claude/CLAUDE.md',
+  '.pi/agent/AGENTS.md'
 ];
 
 for (const relativePath of targets) {
@@ -143,7 +144,8 @@ mkdir -p \
   "$FAKE_HOME/.cursor" \
   "$FAKE_HOME/.codex" \
   "$FAKE_HOME/.config/opencode" \
-  "$FAKE_HOME/.claude"
+  "$FAKE_HOME/.claude" \
+  "$FAKE_HOME/.pi/agent"
 
 echo
 echo "== curl install.sh | sh --version ${VERSION} --yes --agents all =="

package/src/cli.js

@@ -732,7 +732,7 @@ function printHelp() {
   console.log(`${BRAND.displayName} (${PACKAGE_NAME})
 
 ${BRAND.tagline}. ${BRAND.displayName} does not install AI apps — it powers and
-coordinates agents you already have (Cursor, Codex, OpenCode, Claude) with managed
+coordinates agents you already have (Cursor, Codex, OpenCode, Claude, Pi) with managed
 sections, components, backups, and drift repair under ~/.harness.
 
 Bootstrap: see README.md (curl install.sh or npx ${PACKAGE_NAME}).

package/src/global/adapters/pi.js

@@ -0,0 +1,53 @@
+import { resolve } from "node:path";
+import { createManagedConfigAdapter } from "../managed-config-adapter.js";
+
+export const PI_DEFAULT_ROOT_DIR = ".pi/agent";
+export const PI_DEFAULT_CONFIG_FILE = ".pi/agent/AGENTS.md";
+export const PI_CODING_AGENT_DIR_ENV = "PI_CODING_AGENT_DIR";
+
+const CUSTOM_DIR_MESSAGE =
+  `Pi config writes are unsupported when ${PI_CODING_AGENT_DIR_ENV} points away from `
+  + `~/${PI_DEFAULT_ROOT_DIR} (out of scope for Kairo 0.6.0). `
+  + `Unset ${PI_CODING_AGENT_DIR_ENV} to manage the default directory; runtime launches remain available.`;
+
+/** True when PI_CODING_AGENT_DIR is set to a non-default absolute/relative path. */
+export function isCustomPiCodingAgentDir(env = process.env, homeDir) {
+  const raw = env?.[PI_CODING_AGENT_DIR_ENV];
+  if (raw == null || String(raw).trim() === "") return false;
+  if (homeDir == null) return true;
+  return resolve(String(raw).trim()) !== resolve(homeDir, PI_DEFAULT_ROOT_DIR);
+}
+
+export function assertDefaultPiConfigDir(context = {}) {
+  const env = context.env ?? process.env;
+  if (isCustomPiCodingAgentDir(env, context.homeDir)) {
+    throw new Error(CUSTOM_DIR_MESSAGE);
+  }
+}
+
+const managed = createManagedConfigAdapter({
+  id: "pi",
+  label: "Pi",
+  rootDir: PI_DEFAULT_ROOT_DIR,
+  configFile: PI_DEFAULT_CONFIG_FILE
+});
+
+/** Managed adapter for ~/.pi/agent/AGENTS.md; custom PI_CODING_AGENT_DIR fails before writes. */
+export default {
+  ...managed,
+
+  plan(context) {
+    assertDefaultPiConfigDir(context);
+    return managed.plan(context);
+  },
+
+  async apply(context, plan) {
+    assertDefaultPiConfigDir(context);
+    return managed.apply(context, plan);
+  },
+
+  async uninstall(context, stateEntry) {
+    assertDefaultPiConfigDir(context);
+    return managed.uninstall(context, stateEntry);
+  }
+};

package/src/global/agent-capabilities/index.js

@@ -2,6 +2,7 @@ import cursorManaged from "../adapters/cursor.js";
 import codexManaged from "../adapters/codex.js";
 import opencodeManaged from "../adapters/opencode.js";
 import claudeManaged from "../adapters/claude.js";
+import piManaged from "../adapters/pi.js";
 import { createAgentCapabilityAdapter } from "./create-capability-adapter.js";
 
 const cursor = createAgentCapabilityAdapter({
@@ -37,7 +38,16 @@ const claude = createAgentCapabilityAdapter({
   runExecutable: "claude"
 });
 
-const CAPABILITY_ADAPTERS = [cursor, codex, opencode, claude];
+const pi = createAgentCapabilityAdapter({
+  id: "pi",
+  label: "Pi",
+  managedAdapter: piManaged,
+  executable: "pi",
+  opaqueAuth: true,
+  runExecutable: "pi"
+});
+
+const CAPABILITY_ADAPTERS = [cursor, codex, opencode, claude, pi];
 
 export const AGENT_CAPABILITY_IDS = CAPABILITY_ADAPTERS.map((adapter) => adapter.id);
 

package/src/global/brand/index.js

@@ -30,14 +30,16 @@ export const AGENT_LABELS = {
   cursor: "Cursor",
   codex: "Codex",
   opencode: "OpenCode",
-  claude: "Claude Code"
+  claude: "Claude Code",
+  pi: "Pi"
 };
 
 export const AGENT_SYMBOLS = {
   cursor: "◆",
   codex: "◆",
   opencode: "◆",
-  claude: "◆"
+  claude: "◆",
+  pi: "◆"
 };
 
 export const TOKENS = {

package/src/global/dashboard-guidance.js

@@ -150,7 +150,7 @@ export function resolveDashboardRecommendation({
       kind: NEXT_STEP_KINDS.LAUNCH,
       title: "Create a new run",
       message: "Create a new run",
-      detail: "Delegate a task to Cursor, Codex or Claude.",
+      detail: "Delegate a task to Cursor, Codex, Claude, or Pi.",
       targetView: RECOMMENDATION_TARGETS.LAUNCH,
       targetAction: "launch"
     };

package/src/global/global-cli.js

@@ -734,7 +734,7 @@ function printAdapterMatrixReport(report) {
   console.log(commandHeader("adapters — supported agent integrations"));
   console.log(`Home: ${report.homeDir}`);
   console.log("");
-  console.log(`${BRAND.displayName} does not install Cursor, Codex, OpenCode, or Claude Code.`);
+  console.log(`${BRAND.displayName} does not install Cursor, Codex, OpenCode, Claude Code, or Pi.`);
   console.log("It configures managed sections in each agent's config files.");
   console.log("");
   console.log(`Supported: ${report.supportedCount}  Detected: ${report.detectedCount}  Managed: ${report.managedCount}`);

package/src/global/integrations/engram-evidence.js

@@ -3,12 +3,13 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { probeCommand } from "../cli-probe.js";
 
-export const KAIRO_ENGRAM_AGENT_IDS = Object.freeze(["cursor", "codex", "opencode", "claude"]);
+export const KAIRO_ENGRAM_AGENT_IDS = Object.freeze(["cursor", "codex", "opencode", "claude", "pi"]);
 export const ENGRAM_SETUP_SLUG_BY_AGENT = Object.freeze({
   cursor: "cursor",
   codex: "codex",
   opencode: "opencode",
-  claude: "claude-code"
+  claude: "claude-code",
+  pi: "pi"
 });
 export const ENGRAM_MIN_VERSION = "1.19.0";
 export const ENGRAM_MAX_MAJOR = 2;
@@ -110,7 +111,7 @@ export function inspectEngramAgentConfig(agentId, { homeDir = homedir() } = {})
   const conflicts = evidence.filter((item) => item.conflict);
   let status = ENGRAM_INTEGRATION_STATUS.UNCONFIGURED;
   if (conflicts.length > 0) status = ENGRAM_INTEGRATION_STATUS.CONFLICT;
-  else if (evidence.some((item) => item.present && item.kind === "mcp")) {
+  else if (isEngramAgentConfigured(agentId, evidence)) {
     status = ENGRAM_INTEGRATION_STATUS.CONFIGURED;
   }
   return { id: agentId, slug, status, evidence };
@@ -165,9 +166,46 @@ function collectAgentEvidence(agentId, homeDir) {
       fileEvidence(join(homeDir, ".cursor", "rules", "engram.mdc"), "protocol")
     ];
   }
+  if (agentId === "pi") {
+    return [
+      piSettingsPackagesEvidence(join(homeDir, ".pi", "agent", "settings.json")),
+      jsonKeyEvidence(join(homeDir, ".pi", "agent", "mcp.json"), ["mcpServers", "engram"], "mcp")
+    ];
+  }
   throw new Error(`Unsupported Engram agent "${agentId}".`);
 }
 
+function isEngramAgentConfigured(agentId, evidence) {
+  if (agentId === "pi") {
+    return evidence.length > 0 && evidence.every((item) => item.present && !item.conflict);
+  }
+  return evidence.some((item) => item.present && item.kind === "mcp");
+}
+
+function piSettingsPackagesEvidence(path) {
+  const required = ["npm:gentle-engram", "npm:pi-mcp-adapter"];
+  if (!existsSync(path)) {
+    return { path, kind: "settings", present: false, conflict: false, required };
+  }
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    if (data == null || typeof data !== "object" || Array.isArray(data)) {
+      return { path, kind: "settings", present: false, conflict: true, required, detail: "invalid structure" };
+    }
+    const packages = Array.isArray(data.packages) ? data.packages : null;
+    if (packages == null) {
+      return { path, kind: "settings", present: false, conflict: true, required, detail: "invalid structure" };
+    }
+    const normalized = packages.map((entry) => String(entry));
+    const present = required.every((req) =>
+      normalized.some((entry) => entry === req || entry.startsWith(`${req}@`))
+    );
+    return { path, kind: "settings", present, conflict: false, required };
+  } catch {
+    return { path, kind: "settings", present: false, conflict: true, required, detail: "unreadable json" };
+  }
+}
+
 function fileEvidence(path, kind) {
   return { path, kind, present: existsSync(path), conflict: false };
 }

package/src/global/integrations/sdd-destinations.js

@@ -12,8 +12,8 @@ export const SDD_SKILL_IDS = Object.freeze([
   "sdd-archive"
 ]);
 
-export const SDD_MANAGED_AGENT_IDS = Object.freeze(["cursor", "codex", "opencode", "claude"]);
-export const SDD_SHARED_AGENT_IDS = Object.freeze(["cursor", "codex", "opencode"]);
+export const SDD_MANAGED_AGENT_IDS = Object.freeze(["cursor", "codex", "opencode", "claude", "pi"]);
+export const SDD_SHARED_AGENT_IDS = Object.freeze(["cursor", "codex", "opencode", "pi"]);
 export const SDD_PERSONA_IDS = Object.freeze(["off", "teaching"]);
 
 export function resolveSddAgentSelection({

package/src/global/registry.js

@@ -4,8 +4,9 @@ import claude from "./adapters/claude.js";
 import codex from "./adapters/codex.js";
 import cursor from "./adapters/cursor.js";
 import opencode from "./adapters/opencode.js";
+import pi from "./adapters/pi.js";
 
-const ADAPTERS = [cursor, codex, opencode, claude];
+const ADAPTERS = [cursor, codex, opencode, claude, pi];
 
 export const GLOBAL_AGENT_IDS = ADAPTERS.map((adapter) => adapter.id);
 

package/src/global/runtime/execution-adapters/index.js

@@ -2,8 +2,9 @@ import cursor from "./cursor.js";
 import codex from "./codex.js";
 import claude from "./claude.js";
 import opencode from "./opencode.js";
+import pi from "./pi.js";
 
-const EXECUTION_ADAPTERS = [cursor, codex, claude, opencode];
+const EXECUTION_ADAPTERS = [cursor, codex, claude, opencode, pi];
 
 export const EXECUTION_ADAPTER_IDS = EXECUTION_ADAPTERS.map((adapter) => adapter.id);
 

package/src/global/runtime/execution-adapters/pi.js

@@ -0,0 +1,183 @@
+import { createExecutionAdapter, parseNdjsonLine } from "./create-execution-adapter.js";
+import { isExecutableAvailable, probeCommand } from "../../cli-probe.js";
+
+const EXECUTABLE = "pi";
+const READ_ONLY_TOOLS = "read,grep,find,ls";
+
+const LIFECYCLE_KINDS = new Set([
+  "session",
+  "agent_start",
+  "agent_end",
+  "turn_start",
+  "message_start",
+  "message_update",
+  "compaction_start",
+  "compaction_end",
+  "auto_retry_start",
+  "auto_retry_end",
+  "queue_update",
+  "summarization_retry_scheduled",
+  "summarization_retry_attempt_start",
+  "summarization_retry_finished"
+]);
+
+export function buildPiPermissionsArgs(permissions = []) {
+  if (!Array.isArray(permissions) || permissions.length === 0) return [];
+
+  const normalized = [...new Set(permissions.map((entry) => String(entry).toLowerCase()))];
+  if (normalized.length === 1 && normalized[0] === "read-only") {
+    return ["--tools", READ_ONLY_TOOLS];
+  }
+
+  throw new Error(
+    `Pi permissions only support "read-only" in Kairo 0.6.0 (got: ${permissions.join(", ")}). `
+    + "Other aliases are rejected and are never translated to --approve."
+  );
+}
+
+export function buildPiLaunch({ task, cwd, model, permissions = [], env = process.env } = {}) {
+  const args = [
+    "--mode",
+    "json",
+    "--no-session",
+    ...buildPiPermissionsArgs(permissions)
+  ];
+
+  if (model) {
+    args.push("--model", model);
+  }
+
+  args.push(task);
+
+  return {
+    command: EXECUTABLE,
+    args,
+    cwd,
+    env
+  };
+}
+
+export function checkPiAvailability(context = {}) {
+  const env = context.env ?? process.env;
+  const probe = context.probeImpl ?? probeCommand;
+  const availableCheck = context.isAvailableImpl ?? isExecutableAvailable;
+
+  if (!availableCheck(EXECUTABLE, { env })) {
+    return {
+      available: false,
+      compatible: false,
+      launchable: false,
+      reason: 'Pi CLI "pi" is not on PATH.'
+    };
+  }
+
+  const help = probe(EXECUTABLE, ["--help"], { env, timeoutMs: 5000 });
+  const text = `${help.stdout ?? ""}\n${help.stderr ?? ""}`;
+  const hasMode = /--mode\b/.test(text);
+  const hasNoSession = /--no-session\b/.test(text);
+
+  if (!help.ok || !hasMode || !hasNoSession) {
+    return {
+      available: true,
+      compatible: false,
+      launchable: false,
+      reason: "Pi CLI is missing required --mode / --no-session flags for auditable JSON runs."
+    };
+  }
+
+  return {
+    available: true,
+    compatible: true,
+    launchable: true,
+    reason: null
+  };
+}
+
+export function parsePiEventLine(line) {
+  const parsed = parseNdjsonLine(line);
+  if (!parsed || typeof parsed !== "object") return null;
+
+  if (parsed.type === "tool_execution_start") {
+    return {
+      type: "tool_call",
+      tool_name: parsed.toolName ?? "unknown",
+      status: "started",
+      id: parsed.toolCallId ?? null
+    };
+  }
+
+  if (parsed.type === "tool_execution_end") {
+    return {
+      type: "tool_result",
+      tool_name: parsed.toolName ?? "unknown",
+      status: parsed.isError ? "error" : "completed",
+      id: parsed.toolCallId ?? null
+    };
+  }
+
+  if (parsed.type === "tool_execution_update") {
+    return null;
+  }
+
+  if (parsed.type === "message_end") {
+    if (parsed.message?.role !== "assistant") return null;
+    const content = Array.isArray(parsed.message.content)
+      ? parsed.message.content
+        .filter((block) => block?.type === "text")
+        .map((block) => block.text ?? "")
+        .join("")
+      : "";
+    return {
+      type: "assistant",
+      role: "assistant",
+      content
+    };
+  }
+
+  if (parsed.type === "turn_end") {
+    const usage = parsed.message?.usage;
+    if (usage && typeof usage === "object") {
+      const cost = typeof usage.cost === "number"
+        ? usage.cost
+        : typeof usage.cost?.total === "number" ? usage.cost.total : null;
+      return {
+        type: "usage",
+        inputTokens: usage.input ?? usage.inputTokens ?? usage.input_tokens ?? null,
+        outputTokens: usage.output ?? usage.outputTokens ?? usage.output_tokens ?? null,
+        totalTokens: usage.totalTokens ?? usage.total ?? usage.total_tokens ?? null,
+        cost
+      };
+    }
+    return { type: "system", kind: "turn_end" };
+  }
+
+  if (LIFECYCLE_KINDS.has(parsed.type)) {
+    return {
+      type: "system",
+      kind: parsed.type,
+      ...(parsed.reason ? { reason: parsed.reason } : {}),
+      ...(parsed.attempt != null ? { attempt: parsed.attempt } : {})
+    };
+  }
+
+  return {
+    type: "system",
+    kind: parsed.type ?? "unknown"
+  };
+}
+
+export default createExecutionAdapter({
+  id: "pi",
+  label: "Pi",
+  executable: EXECUTABLE,
+  capabilities: {
+    structuredEvents: true,
+    tokens: true,
+    diff: false,
+    cancel: true,
+    transcript: true
+  },
+  checkAvailability: checkPiAvailability,
+  buildLaunch: buildPiLaunch,
+  parseEventLine: parsePiEventLine
+});

package/src/global/runtime/run-cancel-signal.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
 import { runPaths } from "../paths.js";
+import { writeAtomicJson } from "./write-atomic-json.js";
 
 function cancelSignalPath(homeDir, runId) {
   return `${runPaths(homeDir, runId).runDir}/cancel.signal.json`;
@@ -9,7 +10,7 @@ function cancelSignalPath(homeDir, runId) {
 export async function writeCancelSignal(homeDir, runId, payload) {
   const { runDir } = runPaths(homeDir, runId);
   await mkdir(runDir, { recursive: true });
-  await writeFile(cancelSignalPath(homeDir, runId), `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  await writeAtomicJson(cancelSignalPath(homeDir, runId), payload);
 }
 
 export async function readCancelSignal(homeDir, runId) {

package/src/global/runtime/run-store.js

@@ -1,8 +1,9 @@
 import { existsSync } from "node:fs";
-import { appendFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, readdir, readFile } from "node:fs/promises";
 import { harnessHomePaths, runPaths } from "../paths.js";
 import { RUN_STATES, isActiveRunState } from "./run-types.js";
 import { createRunEvent } from "./run-events.js";
+import { writeAtomicJson } from "./write-atomic-json.js";
 
 const writeLocks = new Map();
 
@@ -13,7 +14,7 @@ export function getRunsDir(homeDir) {
 export async function createRunRecord(homeDir, metadata) {
   const { runDir, statePath } = runPaths(homeDir, metadata.runId);
   await mkdir(runDir, { recursive: true });
-  await writeFile(statePath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+  await writeAtomicJson(statePath, metadata);
   return metadata;
 }
 
@@ -34,7 +35,7 @@ export async function writeRunState(homeDir, metadata) {
   const next = previous.then(async () => {
     const { statePath, runDir } = runPaths(homeDir, metadata.runId);
     await mkdir(runDir, { recursive: true });
-    await writeFile(statePath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+    await writeAtomicJson(statePath, metadata);
     return metadata;
   });
   writeLocks.set(key, next.catch(() => {}));

package/src/global/runtime/run-supervisor-lock.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
 import { runPaths } from "../paths.js";
+import { writeAtomicJson } from "./write-atomic-json.js";
 
 function lockPath(homeDir, runId) {
   return `${runPaths(homeDir, runId).runDir}/supervisor.lock.json`;
@@ -9,7 +10,7 @@ function lockPath(homeDir, runId) {
 export async function writeSupervisorLock(homeDir, runId, lock) {
   const { runDir } = runPaths(homeDir, runId);
   await mkdir(runDir, { recursive: true });
-  await writeFile(lockPath(homeDir, runId), `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+  await writeAtomicJson(lockPath(homeDir, runId), lock);
 }
 
 export async function readSupervisorLock(homeDir, runId) {

package/src/global/runtime/write-atomic-json.js

@@ -0,0 +1,51 @@
+import { open as fsOpen, rename as fsRename, unlink as fsUnlink } from "node:fs/promises";
+import { constants } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+function defaultTempPath(targetPath) {
+  const id = randomBytes(8).toString("hex");
+  return join(
+    dirname(targetPath),
+    `.${basename(targetPath)}.${process.pid}.${id}.tmp`
+  );
+}
+
+/**
+ * Atomically replace targetPath with pretty-printed JSON.
+ * Creates a unique temp in the same directory (O_EXCL), writes + fsync,
+ * renames over the destination, and deletes the temp on any failure.
+ */
+export async function writeAtomicJson(targetPath, value, deps = {}) {
+  const open = deps.open ?? fsOpen;
+  const rename = deps.rename ?? fsRename;
+  const unlink = deps.unlink ?? fsUnlink;
+  const createTempPath = deps.createTempPath ?? defaultTempPath;
+
+  const payload = `${JSON.stringify(value, null, 2)}\n`;
+  const tempPath = createTempPath(targetPath);
+  let handle;
+
+  try {
+    handle = await open(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o644);
+    await handle.writeFile(payload, "utf8");
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await rename(tempPath, targetPath);
+  } catch (error) {
+    if (handle) {
+      try {
+        await handle.close();
+      } catch {
+        // Best-effort close before temp cleanup.
+      }
+    }
+    try {
+      await unlink(tempPath);
+    } catch {
+      // Temp may not exist yet or already renamed.
+    }
+    throw error;
+  }
+}