@arcote.tech/arc-cli 0.5.8 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcote.tech/arc-cli",
-  "version": "0.5.8",
+  "version": "0.6.0",
   "description": "CLI tool for Arc framework",
   "module": "index.ts",
   "main": "dist/index.js",
@@ -12,12 +12,12 @@
     "build": "bun build --target=bun ./src/index.ts --outdir=dist --external @arcote.tech/arc --external @arcote.tech/arc-ds --external @arcote.tech/arc-react --external @arcote.tech/platform && chmod +x dist/index.js"
   },
   "dependencies": {
-    "@arcote.tech/arc": "^0.5.8",
-    "@arcote.tech/arc-ds": "^0.5.8",
-    "@arcote.tech/arc-react": "^0.5.8",
-    "@arcote.tech/arc-host": "^0.5.8",
-    "@arcote.tech/arc-adapter-db-sqlite": "^0.5.8",
-    "@arcote.tech/platform": "^0.5.8",
+    "@arcote.tech/arc": "^0.6.0",
+    "@arcote.tech/arc-ds": "^0.6.0",
+    "@arcote.tech/arc-react": "^0.6.0",
+    "@arcote.tech/arc-host": "^0.6.0",
+    "@arcote.tech/arc-adapter-db-sqlite": "^0.6.0",
+    "@arcote.tech/platform": "^0.6.0",
     "@clack/prompts": "^0.9.0",
     "commander": "^11.1.0",
     "chokidar": "^3.5.3",

package/runtime/Dockerfile

@@ -0,0 +1,29 @@
+# arcote/runtime — generic Arc platform runtime container.
+#
+# Image is intentionally version-agnostic. CLI version comes from the
+# ARC_CLI_VERSION env var set by docker-compose (generated per-deploy by
+# `arc platform deploy`), so a single `arcote/runtime:1` tag serves every
+# CLI release. Bumping CLI only requires `bun publish` — no image rebuild.
+#
+# Layout in container:
+#   /app/.arc/cli/<ARC_CLI_VERSION>/   ← arc-cli + direct deps (installed by entrypoint, cached)
+#   /app/.arc/platform/                ← user volume: code, framework + per-module deps
+#   /app/.arc/data/                    ← user volume: sqlite
+#   /root/.bun/install/cache/          ← shared bun store (volume)
+
+FROM oven/bun:1-alpine
+
+# tini for proper signal handling. build-base/python3/git in case any user dep
+# has a native postinstall step (e.g. better-sqlite3). curl for healthchecks.
+RUN apk add --no-cache tini ca-certificates build-base python3 git curl
+
+WORKDIR /app
+
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+EXPOSE 5005
+ENV PORT=5005 \
+    ARC_DEPLOY_API=1
+
+ENTRYPOINT ["tini", "--", "/entrypoint.sh"]

package/runtime/build-and-push.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# build-and-push.sh — manual multi-arch publish of pkrasinski/arc-runtime to Docker Hub.
+#
+# Image is generic (no CLI version baked in) — one tag covers every CLI release.
+# Re-run only when the entrypoint script or base image needs to change.
+#
+# Prereqs: docker buildx + multi-arch builder configured, `docker login` done.
+#
+# Usage: bash build-and-push.sh [tag=1]
+
+set -euo pipefail
+
+TAG="${1:-1}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+docker buildx build \
+  --platform linux/amd64,linux/arm64 \
+  --tag "pkrasinski/arc-runtime:${TAG}" \
+  --tag "pkrasinski/arc-runtime:latest" \
+  --push \
+  "${SCRIPT_DIR}"
+
+echo "✓ Published pkrasinski/arc-runtime:${TAG} (multi-arch)"

package/runtime/entrypoint.sh

@@ -0,0 +1,27 @@
+#!/bin/sh
+# entrypoint.sh — installs arc-cli at ARC_CLI_VERSION (cached per version),
+# then hands off to `arc platform start`. The CLI itself decides between
+# pre-deploy mode (no manifest yet) and full mode based on volume state —
+# no logic for that lives here.
+#
+# bun install of framework peers and per-module deps is done by the CLI in
+# response to /api/deploy/framework and /api/deploy/modules/:name — this
+# script only ensures the CLI binary itself is present.
+
+set -e
+
+: "${ARC_CLI_VERSION:?ARC_CLI_VERSION env var required (set by docker-compose)}"
+
+CLI_DIR="/app/.arc/cli/${ARC_CLI_VERSION}"
+CLI_BIN="${CLI_DIR}/node_modules/@arcote.tech/arc-cli/dist/index.js"
+
+if [ ! -f "$CLI_BIN" ]; then
+  echo "[entrypoint] installing @arcote.tech/arc-cli@${ARC_CLI_VERSION}..."
+  mkdir -p "$CLI_DIR"
+  cd "$CLI_DIR"
+  echo '{"name":"arc-runtime-cli","private":true,"type":"module"}' > package.json
+  bun add "@arcote.tech/arc-cli@${ARC_CLI_VERSION}"
+fi
+
+echo "[entrypoint] starting arc platform (cli=${ARC_CLI_VERSION})"
+exec bun run "$CLI_BIN" platform start

package/src/builder/access-extractor.ts

@@ -0,0 +1,127 @@
+import { spawn } from "bun";
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { basename, join } from "path";
+import type { WorkspacePackage } from "./module-builder";
+import { isContextPackage } from "./module-builder";
+
+// ---------------------------------------------------------------------------
+// access-extractor — runs platform module-access discovery in an ISOLATED
+// subprocess so the global registry (singleton in @arcote.tech/platform) is
+// not polluted between builds. The subprocess imports each context bundle,
+// calls getAllModuleAccess(), and serializes a plain-JSON view to
+// `<arcDir>/access.json`.
+//
+// The `check` callback per rule is NOT serialized — it's a function reference
+// kept inside the server bundle. We only record `{ token: { name }, hasCheck }`.
+// Runtime resolves the actual check via the loaded server bundle at request
+// time.
+// ---------------------------------------------------------------------------
+
+export interface SerializedAccessRule {
+  token: { name: string };
+  hasCheck: boolean;
+}
+
+export interface SerializedModuleAccess {
+  rules: SerializedAccessRule[];
+}
+
+export type SerializedAccessMap = Record<string, SerializedModuleAccess>;
+
+export async function extractAccessMap(
+  arcDir: string,
+  packages: WorkspacePackage[],
+): Promise<SerializedAccessMap> {
+  // Prefer the v0.6 per-module location; fall back to the legacy per-package
+  // dist path used while the build pipeline migration is in progress. The
+  // fallback goes away once module-builder always emits server bundles
+  // under <arcDir>/modules/<safeName>/server.js.
+  const serverBundles = packages
+    .filter((p) => isContextPackage(p.packageJson))
+    .map((p) => {
+      const v06Path = join(arcDir, "modules", basename(p.path), "server.js");
+      const legacyPath = join(p.path, "dist", "server", "main", "index.js");
+      return { name: p.name, path: v06Path, fallback: legacyPath };
+    });
+
+  // Output target — subprocess writes here, we read back.
+  const outPath = join(arcDir, "access.json");
+  mkdirSync(arcDir, { recursive: true });
+
+  // Worker script as a tempfile so we can `bun run <path>` (Bun has no -e flag
+  // for TypeScript). Cleanup in finally.
+  const workerPath = join(tmpdir(), `arc-access-extractor-${Date.now()}.mjs`);
+  writeFileSync(workerPath, WORKER_SOURCE);
+
+  try {
+    const proc = spawn({
+      cmd: ["bun", "run", workerPath],
+      env: {
+        ...process.env,
+        ARC_ACCESS_BUNDLES: JSON.stringify(serverBundles),
+        ARC_ACCESS_OUT: outPath,
+      },
+      stdout: "pipe",
+      stderr: "inherit",
+    });
+    const exit = await proc.exited;
+    if (exit !== 0) {
+      throw new Error(`access-extractor subprocess exited with ${exit}`);
+    }
+    return JSON.parse(readFileSync(outPath, "utf-8")) as SerializedAccessMap;
+  } finally {
+    try {
+      unlinkSync(workerPath);
+    } catch {
+      // best effort
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Worker source (inlined — runs in fresh Bun process)
+// ---------------------------------------------------------------------------
+
+const WORKER_SOURCE = `
+import { existsSync } from "node:fs";
+
+globalThis.ONLY_SERVER = true;
+
+const bundles = JSON.parse(process.env.ARC_ACCESS_BUNDLES || "[]");
+const out = process.env.ARC_ACCESS_OUT;
+if (!out) {
+  console.error("[access-extractor-worker] ARC_ACCESS_OUT not set");
+  process.exit(2);
+}
+
+const platform = await import("@arcote.tech/platform");
+
+for (const { name, path, fallback } of bundles) {
+  const target = existsSync(path) ? path : fallback;
+  if (!target || !existsSync(target)) {
+    // No server bundle on either path — module has no protected access rules
+    // to discover. Skip silently rather than logging a misleading error.
+    continue;
+  }
+  try {
+    await import(target);
+  } catch (e) {
+    console.error("[access-extractor-worker] failed to import", name, "from", target, e);
+    // Continue — partial access map is better than total failure.
+  }
+}
+
+const result = {};
+for (const [name, access] of platform.getAllModuleAccess()) {
+  result[name] = {
+    rules: (access.rules ?? []).map((r) => ({
+      token: { name: r.token?.name ?? "" },
+      hasCheck: typeof r.check === "function",
+    })),
+  };
+}
+
+const { writeFileSync } = await import("node:fs");
+writeFileSync(out, JSON.stringify(result, null, 2) + "\\n");
+`.trim();

package/src/builder/dependency-collector.ts

@@ -0,0 +1,155 @@
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { basename, join } from "path";
+import type { WorkspacePackage } from "./module-builder";
+
+// ---------------------------------------------------------------------------
+// dependency-collector — generates per-module + global framework dep manifests
+// that the runtime container uses to `bun install`.
+//
+// Global manifest (`<arcDir>/package.json` + `bun.lock`): framework peers only,
+// shared across modules so `instanceof` checks survive cross-module imports.
+//
+// Per-module manifest (`<arcDir>/modules/<safeName>/package.json`): everything
+// else this module pulls in (fragments, user libs) — installed in isolation
+// into the module's own node_modules at deploy time.
+// ---------------------------------------------------------------------------
+
+/**
+ * Packages that MUST be singleton across all modules — they define classes
+ * checked with `instanceof` cross-module. Container resolves these from the
+ * platform-level `node_modules/`, not per-module.
+ */
+export const FRAMEWORK_PEERS = [
+  "@arcote.tech/arc",
+  "@arcote.tech/arc-ds",
+  "@arcote.tech/arc-react",
+  "@arcote.tech/platform",
+  "react",
+  "react-dom",
+] as const;
+
+export type FrameworkPeer = (typeof FRAMEWORK_PEERS)[number];
+
+export interface CollectedDeps {
+  /** sha256 of the on-disk manifest+lockfile pair — drives deploy diff. */
+  hash: string;
+  /** Path of the generated package.json. */
+  manifestPath: string;
+}
+
+// ---------------------------------------------------------------------------
+// Global framework peers
+// ---------------------------------------------------------------------------
+
+export function collectFrameworkDeps(
+  arcDir: string,
+  rootDir: string,
+  packages: WorkspacePackage[],
+): CollectedDeps {
+  mkdirSync(arcDir, { recursive: true });
+
+  const versions = resolveFrameworkVersions(rootDir, packages);
+  const manifest = {
+    name: "arc-platform-framework",
+    private: true,
+    type: "module" as const,
+    dependencies: versions,
+  };
+  const manifestPath = join(arcDir, "package.json");
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+
+  // Copy workspace bun.lock so the container can use --frozen-lockfile for
+  // deterministic framework installs. Per-module installs run without it (no
+  // per-module lockfile in MVP).
+  const rootLock = join(rootDir, "bun.lock");
+  const targetLock = join(arcDir, "bun.lock");
+  if (existsSync(rootLock)) {
+    copyFileSync(rootLock, targetLock);
+  }
+
+  const hash = sha256OfFiles([manifestPath, targetLock]);
+  writeFileSync(join(arcDir, ".deps-hash"), hash + "\n");
+  return { hash, manifestPath };
+}
+
+// ---------------------------------------------------------------------------
+// Per-module deps
+// ---------------------------------------------------------------------------
+
+export function collectModuleDeps(
+  arcDir: string,
+  pkg: WorkspacePackage,
+): CollectedDeps {
+  const safeName = basename(pkg.path);
+  const moduleDir = join(arcDir, "modules", safeName);
+  mkdirSync(moduleDir, { recursive: true });
+
+  const pkgDeps = (pkg.packageJson.dependencies ?? {}) as Record<string, string>;
+  const filtered: Record<string, string> = {};
+  const frameworkSet = new Set<string>(FRAMEWORK_PEERS);
+  for (const [name, spec] of Object.entries(pkgDeps)) {
+    if (frameworkSet.has(name)) continue;
+    if (spec.startsWith("workspace:")) continue;
+    filtered[name] = spec;
+  }
+
+  const manifest = {
+    name: `arc-module-${safeName}`,
+    private: true,
+    type: "module" as const,
+    dependencies: filtered,
+  };
+  const manifestPath = join(moduleDir, "package.json");
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+
+  const hash = sha256OfFiles([manifestPath]);
+  writeFileSync(join(moduleDir, ".deps-hash"), hash + "\n");
+  return { hash, manifestPath };
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function resolveFrameworkVersions(
+  rootDir: string,
+  packages: WorkspacePackage[],
+): Record<string, string> {
+  // Workspace root deps win — that's where the user pins versions. Fall back
+  // to whatever a workspace package declared, then `*` as last resort.
+  const rootPkg = JSON.parse(
+    readFileSync(join(rootDir, "package.json"), "utf-8"),
+  );
+  const rootDeps = (rootPkg.dependencies ?? {}) as Record<string, string>;
+  const out: Record<string, string> = {};
+  for (const name of FRAMEWORK_PEERS) {
+    const rootSpec = rootDeps[name];
+    if (rootSpec) {
+      out[name] = rootSpec;
+      continue;
+    }
+    let found: string | undefined;
+    for (const pkg of packages) {
+      const spec = (pkg.packageJson.dependencies ?? {})[name];
+      if (spec) {
+        found = spec;
+        break;
+      }
+    }
+    out[name] = found ?? "*";
+  }
+  return out;
+}
+
+function sha256OfFiles(paths: string[]): string {
+  const hash = createHash("sha256");
+  for (const p of paths.sort()) {
+    if (!existsSync(p)) continue;
+    hash.update(p);
+    hash.update("\0");
+    hash.update(readFileSync(p));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}

package/src/commands/build-shell.ts

@@ -0,0 +1,152 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+
+// ---------------------------------------------------------------------------
+// _build-shell — hidden subcommand used by the runtime container's
+// /api/deploy/framework handler after `bun install` of the framework peers.
+// Discovers every @arcote.tech/* package + react/react-dom under --from and
+// emits one ESM shell bundle per package under --out. The browser then loads
+// these as singletons (shared across all user modules).
+//
+// Decoupled from `arc platform build` (which runs in the user's workspace) —
+// this command operates purely on an installed node_modules tree, with no
+// concept of workspace packages or build cache.
+// ---------------------------------------------------------------------------
+
+export interface BuildShellOptions {
+  out: string;
+  from: string;
+}
+
+const REACT_ENTRIES: Array<[string, string]> = [
+  ["react", `export * from "react";\nimport * as React from "react";\nexport default React;`],
+  ["react-dom", `export * from "react-dom";\nimport * as ReactDOM from "react-dom";\nexport default ReactDOM;`],
+  ["jsx-runtime", `export * from "react/jsx-runtime";`],
+  ["jsx-dev-runtime", `export * from "react/jsx-dev-runtime";`],
+  ["react-dom-client", `export { createRoot, hydrateRoot } from "react-dom/client";`],
+];
+
+const SHELL_BASE_EXTERNAL = [
+  "react",
+  "react-dom",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react-dom/client",
+];
+
+export async function buildShell(opts: BuildShellOptions): Promise<void> {
+  const outDir = opts.out;
+  const fromDir = opts.from;
+
+  if (!existsSync(fromDir)) {
+    console.error(`[_build-shell] --from not found: ${fromDir}`);
+    process.exit(1);
+  }
+
+  mkdirSync(outDir, { recursive: true });
+  const tmpDir = join(outDir, "_tmp");
+  mkdirSync(tmpDir, { recursive: true });
+
+  try {
+    const arcPkgs = discoverArcPackages(fromDir);
+    if (arcPkgs.length === 0) {
+      console.warn("[_build-shell] no @arcote.tech/* packages discovered");
+    }
+
+    console.log(
+      `[_build-shell] building shell for react + ${arcPkgs.length} @arcote.tech/* package(s)`,
+    );
+
+    await buildReactShell(outDir, tmpDir, fromDir);
+    for (const pkg of arcPkgs) {
+      await buildArcEntry(pkg, arcPkgs, outDir, tmpDir, fromDir);
+    }
+
+    console.log(`[_build-shell] done → ${outDir}`);
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Discovery — list every @arcote.tech/* dir under node_modules
+// ---------------------------------------------------------------------------
+
+function discoverArcPackages(fromDir: string): string[] {
+  const arcDir = join(fromDir, "@arcote.tech");
+  if (!existsSync(arcDir)) return [];
+  return readdirSync(arcDir)
+    .filter((name) => existsSync(join(arcDir, name, "package.json")))
+    .map((name) => `@arcote.tech/${name}`);
+}
+
+// ---------------------------------------------------------------------------
+// React shell (separated because it's not under @arcote.tech)
+// ---------------------------------------------------------------------------
+
+async function buildReactShell(
+  outDir: string,
+  tmpDir: string,
+  fromDir: string,
+): Promise<void> {
+  const eps: string[] = [];
+  for (const [name, code] of REACT_ENTRIES) {
+    const f = join(tmpDir, `${name}.ts`);
+    await Bun.write(f, code);
+    eps.push(f);
+  }
+
+  const r = await Bun.build({
+    entrypoints: eps,
+    outdir: outDir,
+    splitting: true,
+    format: "esm",
+    target: "browser",
+    naming: "[name].[ext]",
+    root: fromDir,
+  });
+  if (!r.success) {
+    for (const l of r.logs) console.error(l);
+    throw new Error("React shell build failed");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Per-@arcote.tech package shell
+// ---------------------------------------------------------------------------
+
+async function buildArcEntry(
+  pkg: string,
+  allArcPkgs: string[],
+  outDir: string,
+  tmpDir: string,
+  fromDir: string,
+): Promise<void> {
+  const shortName = pkg.replace("@arcote.tech/", "");
+  const otherExternals = allArcPkgs.filter((p) => p !== pkg);
+
+  const f = join(tmpDir, `${shortName}.ts`);
+  await Bun.write(f, `export * from "${pkg}";\n`);
+
+  // Bun needs to resolve `pkg` from fromDir. Setting `root: fromDir` and
+  // letting Bun walk up node_modules works because @arcote.tech/* lives at
+  // `fromDir/@arcote.tech/<name>`.
+  const r = await Bun.build({
+    entrypoints: [f],
+    outdir: outDir,
+    format: "esm",
+    target: "browser",
+    naming: "[name].[ext]",
+    root: fromDir,
+    external: [...SHELL_BASE_EXTERNAL, ...otherExternals],
+    define: {
+      ONLY_SERVER: "false",
+      ONLY_BROWSER: "true",
+      ONLY_CLIENT: "true",
+    },
+  });
+  if (!r.success) {
+    for (const l of r.logs) console.error(l);
+    throw new Error(`Shell build failed for ${pkg}`);
+  }
+}

package/src/commands/platform-start.ts

@@ -14,13 +14,42 @@ import {
 export async function platformStart(): Promise<void> {
   const ws = resolveWorkspace();
   const port = parseInt(process.env.PORT || "5005", 10);
+  const deployApi = process.env.ARC_DEPLOY_API === "1";
 
-  // Read pre-built manifest
+  // Pre-deploy mode: container started with empty volume (first boot of an
+  // arcote/runtime container — manifest hasn't been pushed yet). Boot a
+  // minimal server so the deploy CLI can reach /api/deploy/* to push the
+  // initial framework + modules. Container restart (after first manifest
+  // commit) re-enters this function with manifest present → full mode.
   const manifestPath = join(ws.modulesDir, "manifest.json");
   if (!existsSync(manifestPath)) {
-    err("No build found. Run `arc platform build` first.");
-    process.exit(1);
+    if (!deployApi) {
+      err("No build found. Run `arc platform build` first.");
+      process.exit(1);
+    }
+    log("Pre-deploy mode — no manifest yet, awaiting first /api/deploy/*");
+    const emptyManifest: BuildManifest = {
+      modules: [],
+      shellHash: "",
+      stylesHash: "",
+      buildTime: new Date().toISOString(),
+    };
+    const platform = await startPlatformServer({
+      ws,
+      port,
+      manifest: emptyManifest,
+      context: null,
+      moduleAccess: new Map(),
+      dbPath: join(ws.rootDir, ".arc", "data", "prod.db"),
+      devMode: false,
+      deployApi: true,
+      arcEntries: [],
+    });
+    ok(`Pre-deploy server on http://localhost:${port}`);
+    registerSignalCleanup(platform);
+    return;
   }
+
   const manifest: BuildManifest = JSON.parse(
     readFileSync(manifestPath, "utf-8"),
   );
@@ -36,7 +65,6 @@ export async function platformStart(): Promise<void> {
 
   // Start server (production mode = aggressive caching, SSE only used for deploy hot-swap)
   const arcEntries = collectArcPeerDeps(ws.packages);
-  const deployApi = process.env.ARC_DEPLOY_API === "1";
   if (deployApi) ok("Deploy API enabled (/api/deploy/*)");
   const platform = await startPlatformServer({
     ws,
@@ -53,7 +81,10 @@ export async function platformStart(): Promise<void> {
   ok(`Server on http://localhost:${port}`);
   if (platform.contextHandler) ok("Commands, queries, WebSocket — all on same port");
 
-  // Cleanup
+  registerSignalCleanup(platform);
+}
+
+function registerSignalCleanup(platform: { stop: () => void }): void {
   const cleanup = () => {
     platform.stop();
     process.exit(0);

package/src/deploy/ansible.ts

@@ -1,4 +1,4 @@
-import { spawn } from "bun";
+import { spawn as nodeSpawn } from "node:child_process";
 import { mkdirSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
@@ -38,31 +38,34 @@ export async function runAnsible(inputs: AnsibleInputs): Promise<void> {
   ].join("\n");
   writeFileSync(join(workDir, "inventory.ini"), inventory);
 
-  const extraVars = [
-    `username=${inputs.target.user}`,
-    `ssh_port=${port}`,
-  ];
-  if (inputs.ansible?.extraAllowedIps?.length) {
-    extraVars.push(
-      `extra_allowed_ips=${JSON.stringify(inputs.ansible.extraAllowedIps)}`,
-    );
-  }
+  // JSON dict so ansible parses types correctly (key=value form makes empty
+  // arrays look like the string "[]" and trips recursive templating).
+  const extraVarsJson = JSON.stringify({
+    username: inputs.target.user,
+    ssh_port: port,
+    extra_allowed_ips: inputs.ansible?.extraAllowedIps ?? [],
+  });
 
-  const proc = spawn({
-    cmd: [
+  // Ansible aborts if its stdout/stderr fds have O_NONBLOCK set — which
+  // happens when our own process is invoked with non-blocking stdio (e.g.
+  // backgrounded by Claude harness, piped through tail). Solution: pipe
+  // stdio (always blocking, Node-managed) and forward chunks manually so the
+  // user still sees ansible output in real time.
+  const exit = await new Promise<number>((resolve, reject) => {
+    const proc = nodeSpawn(
       "ansible-playbook",
-      "-i",
-      "inventory.ini",
-      "site.yml",
-      "-e",
-      extraVars.join(" "),
-    ],
-    cwd: workDir,
-    stdout: "inherit",
-    stderr: "inherit",
-    env: { ...process.env, ANSIBLE_HOST_KEY_CHECKING: "False" },
+      ["-i", "inventory.ini", "site.yml", "-e", extraVarsJson],
+      {
+        cwd: workDir,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { ...process.env, ANSIBLE_HOST_KEY_CHECKING: "False" },
+      },
+    );
+    proc.stdout?.on("data", (chunk: Buffer) => process.stdout.write(chunk));
+    proc.stderr?.on("data", (chunk: Buffer) => process.stderr.write(chunk));
+    proc.on("error", reject);
+    proc.on("exit", (code) => resolve(code ?? 1));
   });
-  const exit = await proc.exited;
   if (exit !== 0) {
     throw new Error(`ansible-playbook failed (exit ${exit})`);
   }