@botbuddy/cli 1.2.3 → 1.4.1

package/src/publish-workflow.test.mjs

@@ -0,0 +1,122 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { readFileSync } from "node:fs";
+
+// BOT-1382: the CLI publish workflow is the artifact under test. These
+// contract assertions make its trigger, working directory, skip behaviour,
+// and post-publish verification reviewable locally, without a YAML parser
+// dependency (the CLI package intentionally has none).
+const wf = readFileSync(
+  new URL("../../.github/workflows/publish-cli-package.yml", import.meta.url),
+  "utf8",
+);
+
+test("BOT-1382: triggers ONLY on main pushes touching cli/ or the workflow — no credential-bearing dispatch", () => {
+  assert.match(wf, /on:/);
+  assert.match(wf, /branches:\s*\[main\]/);
+  assert.match(wf, /- "cli\/\*\*"/);
+  assert.match(wf, /- "\.github\/workflows\/publish-cli-package\.yml"/);
+  // workflow_dispatch is intentionally NOT enabled: it accepts an arbitrary
+  // --ref, so a feature branch could run its own (guard-stripped) workflow with
+  // NPM_TOKEN. The on: block must not declare it.
+  assert.doesNotMatch(wf, /^\s*workflow_dispatch:/m);
+});
+
+test("BOT-1382: read-only contents permission and a static, non-cancelling concurrency group", () => {
+  assert.match(wf, /permissions:\s*\n\s*contents: read/);
+  assert.match(wf, /cancel-in-progress: false/);
+  // A STATIC group serializes publishes so the backward-move guard is correct
+  // (a per-commit key would let runs race the guard and corrupt the dist-tag).
+  assert.match(wf, /group: publish-cli-package\n/);
+  assert.doesNotMatch(wf, /group: publish-cli-package-\$\{\{ github\.sha \}\}/);
+});
+
+test("BOT-1382: Node 20 on the public npm registry", () => {
+  assert.match(wf, /node-version: 20/);
+  assert.match(wf, /registry-url: "https:\/\/registry\.npmjs\.org"/);
+});
+
+test("BOT-1382: fails loudly on a missing NPM_TOKEN and never echoes it", () => {
+  assert.match(wf, /NPM_TOKEN repo secret is not set/);
+  assert.match(wf, /secrets\.NPM_TOKEN/);
+  // The token must only ever flow through env, never be printed.
+  assert.doesNotMatch(wf, /echo[^\n]*\$\{?NPM_TOKEN/);
+});
+
+test("BOT-1382: reads name and version dynamically and never hard-codes the version", () => {
+  assert.match(wf, /require\('\.\/cli\/package\.json'\)\.name/);
+  assert.match(wf, /require\('\.\/cli\/package\.json'\)\.version/);
+  assert.doesNotMatch(wf, /1\.4\.0/);
+});
+
+test("BOT-1382: prerelease is classified structurally, not by a raw hyphen", () => {
+  assert.match(wf, /publish-equal\.mjs" --is-prerelease/);
+  // The naive raw-hyphen classifier must be gone (build metadata like
+  // 1.4.0+build-1 is a stable release).
+  assert.doesNotMatch(wf, /\[\[ "\$LOCAL" == \*-\* \]\]/);
+});
+
+test("BOT-1382: the exact-version probe fails closed — only E404 means unpublished", () => {
+  const check = wf.slice(wf.indexOf("Decide publish vs skip"), wf.indexOf("Guard against moving a dist-tag backward"));
+  assert.match(check, /E404/);
+  assert.match(check, /registry error/);
+  assert.doesNotMatch(check, /npm view "\$\{PKG_NAME\}@\$\{LOCAL\}" version >\/dev\/null 2>&1/);
+});
+
+test("BOT-1382: runs the full CLI test suite before publishing", () => {
+  assert.match(wf, /node --test cli\/src\/\*\.test\.mjs/);
+});
+
+test("BOT-1382: performs an npm pack dry-run from cli/ before publishing", () => {
+  assert.match(wf, /working-directory: cli/);
+  assert.match(wf, /npm pack --dry-run/);
+});
+
+test("BOT-1382: skips an already-published version and otherwise publishes with public access", () => {
+  assert.match(wf, /npm view "\$\{PKG_NAME\}@\$\{LOCAL\}" version/);
+  assert.match(wf, /npm publish --access public/);
+  assert.match(wf, /if: steps\.check\.outputs\.published == 'false'/);
+});
+
+test("BOT-1382: verifies the public artifact — exact version, latest tag, and profile/wait --help", () => {
+  assert.match(wf, /npm view "\$\{PKG_NAME\}@\$\{LOCAL\}" version/);
+  assert.match(wf, /npm view "\$\{PKG_NAME\}@latest" version/);
+  assert.match(wf, /profile --help/);
+  assert.match(wf, /wait --help/);
+});
+
+test("BOT-1382: a changed CLI that reuses a published version fails instead of silently skipping", () => {
+  // Only a byte-identical published package is an idempotent skip; a changed
+  // cli/ that reused a published (immutable) version must fail loudly. The
+  // decision is delegated to the unit-tested publish-equal helper.
+  assert.match(wf, /dist\.tarball/);
+  assert.match(wf, /versions are immutable/);
+  assert.match(wf, /cli\/src\/publish-equal\.mjs/);
+});
+
+test("BOT-1382: prereleases publish under a non-latest tag and must not move latest", () => {
+  assert.match(wf, /--tag next/);
+  assert.match(wf, /moved the latest dist-tag/);
+});
+
+test("BOT-1382: a publish that would move a dist-tag backward is refused (latest for stable, next for prerelease)", () => {
+  assert.match(wf, /Guard against moving a dist-tag backward/);
+  assert.match(wf, /publish-equal\.mjs" --gt/);
+  assert.match(wf, /move the \$\{TAG\} dist-tag backward/);
+  // The guarded tag is chosen by prerelease-ness: next for prereleases, latest otherwise.
+  assert.match(wf, /if \[\[ "\$PRERELEASE" == "true" \]\]; then TAG="next"; else TAG="latest"; fi/);
+});
+
+test("BOT-1382: publishing is restricted to main even via workflow_dispatch", () => {
+  assert.match(wf, /must only run on main/);
+  assert.match(wf, /GITHUB_REF.*!= "refs\/heads\/main"|"\$\{GITHUB_REF\}" != "refs\/heads\/main"/);
+});
+
+test("BOT-1382: the backward-move guard reads the dist-tag fail-closed — a registry error aborts, only E404 is a first publish", () => {
+  // A non-404 read failure must abort rather than be treated as "no tag".
+  const guard = wf.slice(wf.indexOf("Guard against moving a dist-tag backward"));
+  assert.match(guard, /E404/);
+  assert.match(guard, /registry error/);
+  // The guard must NOT swallow read errors into an empty "first publish".
+  assert.doesNotMatch(guard.slice(0, guard.indexOf("Publish to npm")), /2>\/dev\/null \|\| true/);
+});

package/src/quiet-runner.mjs

@@ -0,0 +1,134 @@
+// BOT-816 — host-side quiet command runner.
+//
+// This module deliberately owns process polling outside an LLM.  It is
+// dependency-free so adapters can use it from the published CLI as well as
+// embed it in an editor integration.  The API boundary sends only metadata;
+// the complete output remains in the receipt file.
+import { createReadStream } from "node:fs";
+import { appendFile, mkdir, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+
+const MAX_SNAPSHOT_CHARS = 800;
+const MAX_FAILURE_TAIL_BYTES = 2048;
+const MAX_FAILURE_CAPTURE_BYTES = 64 * 1024;
+
+function boundedText(value, maxChars = 64) {
+  const text = String(value ?? "");
+  return text.length <= maxChars ? text : `${text.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+
+export function boundedSnapshot({ status, elapsedSeconds, transition, receiptPath, nextWakeCondition }) {
+  // Bound fields before serializing so callers always receive parseable JSON.
+  // 64-character fields remain comfortably below the 800-character contract,
+  // even when every character needs JSON escaping.
+  return JSON.stringify({
+    status: boundedText(status, 32),
+    elapsed_seconds: Math.max(0, Math.floor(elapsedSeconds)),
+    last_meaningful_transition: boundedText(transition, 64) || null,
+    receipt_path: boundedText(receiptPath, 64),
+    next_wake_condition: boundedText(nextWakeCondition, 64),
+  });
+}
+
+function redactFailureText(text) {
+  return String(text)
+    .replace(/(authorization\s*:\s*bearer\s+)[^\s,;]+/gi, "$1[REDACTED]")
+    .replace(/((?:"|')(?:api[_-]?key|token|password|secret)(?:"|')\s*:\s*(?:"|'))[^"']*((?:"|'))/gi, "$1[REDACTED]$2")
+    .replace(/((?:api[_-]?key|token|password|secret)\s*[=:]\s*)[^\s]+/gi, "$1[REDACTED]")
+    .replace(/\b(?:bb_[A-Za-z0-9_-]+|sk-[A-Za-z0-9_-]+|ghp_[A-Za-z0-9_-]+)\b/g, "[REDACTED]");
+}
+
+export function failureTail(text) {
+  // Redact before taking the tail: a long secret may otherwise lose its
+  // `token=`/`Authorization:` prefix at the truncation boundary.
+  const redacted = redactFailureText(text);
+  return Buffer.from(redacted).subarray(-MAX_FAILURE_TAIL_BYTES).toString("utf8");
+}
+
+function appendFailureCapture(current, chunk) {
+  // Redact the combined bounded history before truncating it. Keeping the
+  // unredacted (but capped) boundary context lets `token=` in one poll and its
+  // value in the next poll be recognised as one credential before its label
+  // would otherwise fall outside the capture window.
+  const combined = current + String(chunk);
+  const redacted = redactFailureText(combined);
+  const safe = redacted === combined ? combined : redacted;
+  return safe.length <= MAX_FAILURE_CAPTURE_BYTES ? safe : safe.slice(-MAX_FAILURE_CAPTURE_BYTES);
+}
+
+async function sha256File(path) {
+  return await new Promise((resolve, reject) => {
+    const hash = createHash("sha256");
+    const input = createReadStream(path);
+    input.on("data", (chunk) => hash.update(chunk));
+    input.once("error", reject);
+    input.once("end", () => resolve(hash.digest("hex")));
+  });
+}
+
+export class QuietRunner {
+  constructor({ launch, notify, heartbeat, artifactDir, now = () => Date.now(), pollIntervalMs = 1_000 }) {
+    this.launch = launch;
+    this.notify = notify;
+    this.heartbeat = heartbeat;
+    this.artifactDir = artifactDir;
+    this.now = now;
+    this.pollIntervalMs = pollIntervalMs;
+  }
+
+  async run({ runId = randomUUID(), command, receiptPath, receiptUri, onTransition }) {
+    // `receiptPath` is the local artifact path. A registered command also has
+    // a server-issued receipt URI; that URI is metadata, never a filesystem
+    // path. Keeping the two separate prevents `resolve("receipt://…")` from
+    // turning a valid upload target into an invalid local absolute path.
+    const registeredReceiptUri = receiptUri ?? (typeof receiptPath === "string" && /^(artifact|receipt):\/\//.test(receiptPath) ? receiptPath : undefined);
+    const path = resolve(registeredReceiptUri ? `${this.artifactDir}/${runId}.log` : (receiptPath ?? `${this.artifactDir}/${runId}.log`));
+    const reportedReceiptPath = registeredReceiptUri ?? path;
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, "");
+    const started = this.now();
+    const process = await this.launch(command);
+    let pollCount = 0;
+    let unchangedPollCount = 0;
+    let lastTransition = "started";
+    let outputCharacters = 0;
+    let failureCapture = "";
+    let terminal;
+
+    for await (const update of process.poll(this.pollIntervalMs)) {
+      pollCount += 1;
+      if (update.output) {
+        outputCharacters += update.output.length;
+        failureCapture = appendFailureCapture(failureCapture, update.output);
+        await appendFile(path, update.output);
+      }
+      if (update.transition) {
+        lastTransition = update.transition;
+        unchangedPollCount = 0;
+        const snapshot = boundedSnapshot({ status: "running", elapsedSeconds: (this.now() - started) / 1000, transition: lastTransition, receiptPath: reportedReceiptPath, nextWakeCondition: "terminal_failure_approval_or_transition" });
+        await onTransition?.({ run_id: runId, status: "running", meaningful_transition: lastTransition, snapshot, poll_count: pollCount, unchanged_poll_count: unchangedPollCount, receipt_path: reportedReceiptPath });
+        await this.notify?.({ run_id: runId, reason: "meaningful_transition", snapshot });
+      } else {
+        unchangedPollCount += 1;
+      }
+      await this.heartbeat?.({ run_id: runId, status: "running" });
+      if (update.terminal) { terminal = update; break; }
+    }
+
+    const size = (await stat(path)).size;
+    const receipt = { path, artifact_uri: registeredReceiptUri, sha256: await sha256File(path), bytes: size };
+    const status = terminal?.exitCode === 0 ? "succeeded" : "failed";
+    const result = {
+      run_id: runId, status, exit_code: terminal?.exitCode ?? 1, receipt_path: reportedReceiptPath,
+      receipt, poll_count: pollCount, unchanged_poll_count: unchangedPollCount,
+      output_characters: outputCharacters, original_output_tokens: Math.ceil(outputCharacters / 4),
+      delivered_output_tokens: 0, truncated: outputCharacters > 0,
+      failure: status === "failed" ? { exit_code: terminal?.exitCode ?? 1, receipt_path: reportedReceiptPath, tail: failureTail(failureCapture) } : undefined,
+    };
+    await onTransition?.(result);
+    await this.notify?.({ run_id: runId, reason: status === "failed" ? "failure" : "terminal", ...(status === "failed" ? { failure: result.failure } : { receipt_path: reportedReceiptPath }) });
+    await this.heartbeat?.({ run_id: runId, status: "terminal" });
+    return result;
+  }
+}

package/src/quiet-runner.test.mjs

@@ -0,0 +1,109 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { QuietRunner, boundedSnapshot, failureTail } from "./quiet-runner.mjs";
+
+test("quiet runner writes complete output while waking only for transitions and terminal state", async () => {
+  const artifactDir = await mkdtemp(join(tmpdir(), "botbuddy-quiet-runner-"));
+  const notifications = []; const heartbeats = [];
+  const runner = new QuietRunner({
+    artifactDir, now: (() => { let now = 0; return () => (now += 1_000); })(),
+    launch: async () => ({ async *poll() { yield { output: "waiting\\n" }; yield { output: "ready\\n", transition: "tests_started" }; yield { output: "done\\n", terminal: true, exitCode: 0 }; } }),
+    notify: async (value) => notifications.push(value), heartbeat: async (value) => heartbeats.push(value),
+  });
+  const result = await runner.run({ runId: "run-1", command: ["pnpm", "test"] });
+  assert.equal(result.status, "succeeded");
+  assert.equal(await readFile(result.receipt_path, "utf8"), "waiting\\nready\\ndone\\n");
+  assert.equal(notifications.length, 2, "unchanged polls never wake the agent");
+  assert.equal(notifications[0].reason, "meaningful_transition");
+  assert.equal(notifications[1].reason, "terminal");
+  assert.equal(heartbeats.at(-1).status, "terminal");
+});
+
+test("quiet runner sanitizes failure and snapshots stay bounded", async () => {
+  const artifactDir = await mkdtemp(join(tmpdir(), "botbuddy-quiet-runner-"));
+  const runner = new QuietRunner({ artifactDir, launch: async () => ({ async *poll() { yield { output: `token=super-secret\\n${"x".repeat(3_000)}`, terminal: true, exitCode: 1 }; } }) });
+  const result = await runner.run({ runId: "run-2", command: ["false"] });
+  assert.equal(result.failure.exit_code, 1);
+  assert.equal(result.failure.tail.length <= 2048, true);
+  assert.equal(result.failure.tail.includes("super-secret"), false);
+  assert.equal(boundedSnapshot({ status: "running", elapsedSeconds: 1, transition: "x".repeat(5_000), receiptPath: "receipt://x", nextWakeCondition: "terminal" }).length <= 800, true);
+});
+
+test("quiet runner redacts bearer headers and known credential prefixes", () => {
+  const tail = failureTail("Authorization: Bearer bb_live_abc123\\nsk-proj-secret\\nghp_githubsecret\\ntoken=plain-secret\\n{\"password\":\"hunter2\",\"api_key\":\"opaque-secret\"}");
+  assert.equal(tail.includes("bb_live_abc123"), false);
+  assert.equal(tail.includes("sk-proj-secret"), false);
+  assert.equal(tail.includes("ghp_githubsecret"), false);
+  assert.equal(tail.includes("plain-secret"), false);
+  assert.equal(tail.includes("hunter2"), false);
+  assert.equal(tail.includes("opaque-secret"), false);
+  assert.match(tail, /Authorization: Bearer \[REDACTED\]/);
+});
+
+test("quiet runner redacts a credential even when it crosses the failure-tail boundary", () => {
+  const secret = "x".repeat(3_000);
+  const tail = failureTail(`token=${secret}`);
+  assert.equal(tail.includes(secret.slice(-64)), false);
+  assert.match(tail, /token=\[REDACTED\]/);
+});
+
+test("quiet runner redacts a credential before bounded capture drops its label", async () => {
+  const artifactDir = await mkdtemp(join(tmpdir(), "botbuddy-quiet-runner-"));
+  const secret = "x".repeat(70_000);
+  const runner = new QuietRunner({ artifactDir, launch: async () => ({ async *poll() { yield { output: `token=${secret}`, terminal: true, exitCode: 1 }; } }) });
+  const result = await runner.run({ runId: "large-secret", command: ["false"] });
+  assert.equal(result.failure.tail.includes(secret.slice(-64)), false);
+  assert.match(result.failure.tail, /token=\[REDACTED\]/);
+});
+
+test("quiet runner redacts a credential whose label and value arrive in separate polls", async () => {
+  const artifactDir = await mkdtemp(join(tmpdir(), "botbuddy-quiet-runner-"));
+  const secret = "x".repeat(70_000);
+  const runner = new QuietRunner({ artifactDir, launch: async () => ({ async *poll() {
+    yield { output: "token=" };
+    yield { output: secret, terminal: true, exitCode: 1 };
+  } }) });
+  const result = await runner.run({ runId: "split-large-secret", command: ["false"] });
+  assert.equal(result.failure.tail.includes(secret.slice(-64)), false);
+  assert.match(result.failure.tail, /token=\[REDACTED\]/);
+});
+
+test("bounded snapshots remain parseable JSON when fields are oversized", () => {
+  const snapshot = boundedSnapshot({ status: "running", elapsedSeconds: 1, transition: '"'.repeat(5_000), receiptPath: "receipt://" + "\\".repeat(5_000), nextWakeCondition: "x".repeat(5_000) });
+  assert.equal(snapshot.length <= 800, true);
+  assert.equal(JSON.parse(snapshot).status, "running");
+});
+
+test("quiet runner keeps only bounded failure state while recording a large receipt", async () => {
+  const artifactDir = await mkdtemp(join(tmpdir(), "botbuddy-quiet-runner-"));
+  const output = "x".repeat(200_000);
+  const runner = new QuietRunner({ artifactDir, launch: async () => ({ async *poll() { yield { output, terminal: true, exitCode: 1 }; } }) });
+  const result = await runner.run({ runId: "large-output", command: ["false"] });
+  assert.equal(result.output_characters, output.length);
+  assert.equal((await readFile(result.receipt_path)).length, output.length);
+  assert.equal(result.failure.tail.length <= 2048, true);
+});
+
+test("quiet runner preserves a registered receipt URI while writing its local artifact", async () => {
+  const artifactDir = await mkdtemp(join(tmpdir(), "botbuddy-quiet-runner-"));
+  const transitions = [];
+  const runner = new QuietRunner({
+    artifactDir,
+    launch: async () => ({ async *poll() { yield { output: "complete\\n", transition: "finished", terminal: true, exitCode: 0 }; } }),
+  });
+
+  const result = await runner.run({
+    runId: "registered-receipt",
+    command: ["pnpm", "test"],
+    receiptPath: "receipt://tenant/registered-receipt",
+    onTransition: async (transition) => transitions.push(transition),
+  });
+
+  assert.equal(result.receipt_path, "receipt://tenant/registered-receipt");
+  assert.equal(result.receipt.artifact_uri, "receipt://tenant/registered-receipt");
+  assert.equal(await readFile(result.receipt.path, "utf8"), "complete\\n");
+  assert.equal(transitions[0].receipt_path, "receipt://tenant/registered-receipt");
+});

package/src/run.mjs

@@ -0,0 +1,239 @@
+// BOT-1350 — a durable local owner for receipt-bearing commands.
+//
+// The launcher intentionally exits after it has registered a run and handed a
+// sealed context to a detached worker.  The worker creates its own process
+// group for the workload, writes exactly one receipt, and is the only process
+// allowed to call update_command_run.  A bb-wait is therefore a notification
+// mechanism, never the owner of a child process.
+
+import { createHash, randomUUID } from "crypto";
+import { mkdir, readFile, writeFile, chmod, unlink, stat, rename } from "fs/promises";
+import { dirname, join } from "path";
+import { homedir } from "os";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+import { callToolJson } from "./api.mjs";
+
+export const RUN_SCHEMA_VERSION = 1;
+export const EXIT = Object.freeze({ OK: 0, INVALID: 4, BACKEND: 5, INTERNAL: 7 });
+export const DEFAULT_TIMEOUT_SECONDS = 8 * 60 * 60;
+export const TIMEOUT_GRACE_MS = 5_000;
+const MAX_CAPTURE_BYTES = 8_192;
+
+export function parseRunArgs(argv) {
+  const opts = { sessionId: null, environment: null, category: "validation", kind: "other", expectedDuration: 0, timeout: DEFAULT_TIMEOUT_SECONDS, rerunReason: null, json: false };
+  const errors = [];
+  const separator = argv.indexOf("--");
+  const flags = separator === -1 ? argv : argv.slice(0, separator);
+  const command = separator === -1 ? [] : argv.slice(separator + 1);
+  const value = (name, index) => {
+    if (flags[index + 1] == null) { errors.push(`${name} needs a value`); return null; }
+    return flags[index + 1];
+  };
+  for (let i = 0; i < flags.length; i++) {
+    const flag = flags[i];
+    switch (flag) {
+      case "--session-id": opts.sessionId = value(flag, i); i++; break;
+      case "--environment": opts.environment = value(flag, i); i++; break;
+      case "--category": opts.category = value(flag, i); i++; break;
+      case "--kind": opts.kind = value(flag, i); i++; break;
+      case "--expected-duration": opts.expectedDuration = Number(value(flag, i)); i++; break;
+      case "--timeout": opts.timeout = Number(value(flag, i)); i++; break;
+      case "--rerun-reason": {
+        const raw = value(flag, i); i++;
+        try {
+          const parsed = JSON.parse(raw);
+          if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("must be a JSON object");
+          opts.rerunReason = parsed;
+        } catch (error) { errors.push(`--rerun-reason must be a JSON object (${error instanceof Error ? error.message : String(error)})`); }
+        break;
+      }
+      case "--json": opts.json = true; break;
+      default: errors.push(`unknown option: ${flag}`);
+    }
+  }
+  if (!opts.sessionId) errors.push("--session-id is required (from register_agent)");
+  if (!opts.environment || !["local", "preview", "staging", "production", "none"].includes(opts.environment)) errors.push("--environment must be local, preview, staging, production, or none");
+  if (!command.length) errors.push("a workload is required after --");
+  if (!Number.isInteger(opts.expectedDuration) || opts.expectedDuration < 0) errors.push("--expected-duration must be a non-negative integer");
+  if (!Number.isInteger(opts.timeout) || opts.timeout <= 0 || opts.timeout > DEFAULT_TIMEOUT_SECONDS) errors.push(`--timeout must be a positive integer <= ${DEFAULT_TIMEOUT_SECONDS}`);
+  return { opts, command, errors };
+}
+
+export function terminalStatus({ exitCode, signal, timedOut = false, ownerLost = false }) {
+  if (ownerLost) return "owner_lost";
+  if (timedOut) return "timed_out";
+  if (signal) return "cancelled";
+  return exitCode === 0 ? "success" : "failure";
+}
+
+export function commandHash(command) { return createHash("sha256").update(JSON.stringify(command)).digest("hex"); }
+export function environmentHash(cwd, environment) { return createHash("sha256").update(`${cwd}\0${environment}`).digest("hex"); }
+export function receiptPath(runId) { return join(homedir(), ".botbuddy", "command-runs", `${runId}.receipt.json`); }
+export function contextPath(runId) { return join(homedir(), ".botbuddy", "command-runs", `${runId}.context.json`); }
+
+async function writeJson(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  // Write-then-rename so a concurrent reader (cancelRun reading the context
+  // file, or a poller) never observes a torn/empty file mid-write. rename(2)
+  // is atomic within a directory, so readers see either the old or the new
+  // complete JSON, never a partial one.
+  const tmp = `${path}.${process.pid}.tmp`;
+  await writeFile(tmp, JSON.stringify(value), { mode: 0o600 });
+  await chmod(tmp, 0o600);
+  await rename(tmp, path);
+}
+
+function oneLine(value, pretty) { process.stdout.write(`${JSON.stringify(value, null, pretty ? 2 : 0)}\n`); }
+
+function workerInvocation(context) {
+  const bin = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "botbuddy.mjs");
+  return [process.execPath, [bin, "run", "--worker", context]];
+}
+
+export async function launchRun(argv, { cwd = process.cwd(), spawnImpl = spawn, call = callToolJson } = {}) {
+  const { opts, command, errors } = parseRunArgs(argv);
+  if (errors.length) return { exitCode: EXIT.INVALID, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", errors, exit_code: EXIT.INVALID } };
+  const runId = randomUUID();
+  const registration = await call("register_command", {
+    session_id: opts.sessionId, run_id: runId, tool_category: opts.category,
+    command_hash: commandHash(command), environment_hash: environmentHash(cwd, opts.environment),
+    environment: opts.environment, command_kind: opts.kind, expected_duration_seconds: opts.expectedDuration,
+    rerun_reason: opts.rerunReason,
+  });
+  if (!registration.ok || registration.isError || !registration.data?.accepted || !registration.data?.run_credential) {
+    return { exitCode: EXIT.BACKEND, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", run_id: runId, error: registration.data?.error ?? registration.error ?? "durable_owner_not_established", exit_code: EXIT.BACKEND } };
+  }
+  const context = contextPath(runId);
+  const receipt = receiptPath(runId);
+  await writeJson(context, { schema_version: RUN_SCHEMA_VERSION, context_path: context, run_id: runId, run_credential: registration.data.run_credential, receipt_upload: registration.data.receipt_upload, command, cwd, timeout_seconds: opts.timeout, receipt_path: receipt, launched_at: new Date().toISOString() });
+  const [file, args] = workerInvocation(context);
+  try {
+    const worker = spawnImpl(file, args, { detached: true, stdio: "ignore", windowsHide: true });
+    worker.unref();
+  } catch (error) {
+    await call("update_command_run", { run_id: runId, run_credential: registration.data.run_credential, status: "owner_lost", invalidated_reason: `launcher_failed:${error instanceof Error ? error.message : String(error)}` });
+    return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "owner_lost", run_id: runId, exit_code: EXIT.INTERNAL } };
+  }
+  return { exitCode: EXIT.OK, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "launched", run_id: runId, session_id: opts.sessionId, durable_owner: "detached_worker", receipt_path: receipt, reentry: "update_command_run publishes the terminal callback for this run_id", exit_code: EXIT.OK } };
+}
+
+export async function runWorker(contextFile, { spawnImpl = spawn, call = callToolJson } = {}) {
+  const context = JSON.parse(await readFile(contextFile, "utf8"));
+  const startedAt = new Date().toISOString();
+  let timedOut = false;
+  let child;
+  try {
+    child = spawnImpl(context.command[0], context.command.slice(1), { cwd: context.cwd, detached: true, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+  } catch (error) {
+    return finalize(context, { status: "owner_lost", startedAt, endedAt: new Date().toISOString(), exitCode: null, signal: null, reason: `workload_spawn_failed:${error instanceof Error ? error.message : String(error)}` }, call);
+  }
+  // A failed spawn can report through the child `error` event on the next turn.
+  // Subscribe before any filesystem I/O so a busy parallel test run (or a real
+  // fast failure) cannot lose the sole terminal event.
+  const completion = waitForChild(child);
+  await writeJson(context.context_path, { ...context, worker_pid: process.pid, workload_pid: child.pid });
+  const capture = boundedCapture();
+  child.stdout?.on("data", (chunk) => capture.append(chunk));
+  child.stderr?.on("data", (chunk) => capture.append(chunk));
+  let killTimer;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    terminateProcessGroup(child, "SIGTERM");
+    killTimer = setTimeout(() => terminateProcessGroup(child, "SIGKILL"), context.timeout_grace_ms ?? TIMEOUT_GRACE_MS);
+  }, context.timeout_seconds * 1000);
+  const result = await completion;
+  clearTimeout(timer);
+  clearTimeout(killTimer);
+  if (result.error) {
+    return finalize(context, { status: "owner_lost", startedAt, endedAt: new Date().toISOString(), exitCode: null, signal: null, reason: `workload_spawn_failed:${result.error.message}`, output: capture.output, outputCharacters: capture.characters }, call);
+  }
+  const status = terminalStatus({ ...result, timedOut });
+  return finalize(context, { status, startedAt, endedAt: new Date().toISOString(), exitCode: result.exitCode, signal: result.signal, output: capture.output, outputCharacters: capture.characters }, call);
+}
+
+function boundedCapture() {
+  let tail = Buffer.alloc(0);
+  let characters = 0;
+  return {
+    append(chunk) {
+      const bytes = Buffer.from(chunk);
+      characters += bytes.toString("utf8").length;
+      tail = Buffer.concat([tail, bytes]).subarray(-MAX_CAPTURE_BYTES);
+    },
+    get output() { return tail.toString("utf8"); },
+    get characters() { return characters; },
+  };
+}
+
+function terminateProcessGroup(child, signal) {
+  try { process.kill(-child.pid, signal); } catch { try { child.kill?.(signal); } catch { /* already exited */ } }
+}
+
+function waitForChild(child) {
+  return new Promise((resolve) => {
+    const close = (exitCode, signal) => { child.removeListener("error", failed); resolve({ exitCode, signal }); };
+    const failed = (error) => { child.removeListener("close", close); resolve({ error: error instanceof Error ? error : new Error(String(error)) }); };
+    child.once("close", close);
+    child.once("error", failed);
+  });
+}
+
+export async function cancelRun(runId, { call = callToolJson } = {}) {
+  const context = JSON.parse(await readFile(contextPath(runId), "utf8"));
+  if (!Number.isInteger(context.workload_pid) || context.workload_pid <= 0) {
+    return { exitCode: EXIT.INVALID, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", run_id: runId, error: "durable owner has not started a workload", exit_code: EXIT.INVALID } };
+  }
+  try {
+    process.kill(-context.workload_pid, "SIGTERM");
+  } catch (error) {
+    await call("update_command_run", { run_id: context.run_id, run_credential: context.run_credential, status: "owner_lost", invalidated_reason: `cancel_owner_unreachable:${error instanceof Error ? error.message : String(error)}` });
+    return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "owner_lost", run_id: runId, exit_code: EXIT.INTERNAL } };
+  }
+  return { exitCode: EXIT.OK, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "cancellation_requested", run_id: runId, exit_code: EXIT.OK } };
+}
+
+async function finalize(context, state, call) {
+  const boundedLog = String(state.output ?? "").slice(-8192);
+  const outputCharacters = state.outputCharacters ?? String(state.output ?? "").length;
+  const receipt = { schema_version: RUN_SCHEMA_VERSION, run_id: context.run_id, status: state.status, started_at: state.startedAt, ended_at: state.endedAt, exit_code: state.exitCode, signal: state.signal, recovery_command: state.status === "failure" ? `botbuddy run --session-id <new-session-id> --environment local -- ${context.command.map((x) => JSON.stringify(x)).join(" ")}` : null, bounded_log: boundedLog, output_characters: outputCharacters, reason: state.reason ?? null };
+  await writeJson(context.receipt_path, receipt);
+  const bytes = await stat(context.receipt_path);
+  const sha256 = createHash("sha256").update(await readFile(context.receipt_path)).digest("hex");
+  const apiStatus = ({ success: "succeeded", failure: "failed", cancelled: "cancelled", timed_out: "timed_out", owner_lost: "owner_lost" })[state.status];
+  const update = { run_id: context.run_id, run_credential: context.run_credential, status: apiStatus, exit_code: state.exitCode ?? undefined, invalidated_reason: state.reason ?? (state.status === "timed_out" ? "timeout" : state.status === "owner_lost" ? "owner_lost" : undefined), receipt_path: context.receipt_upload, receipt_content_type: "application/json", receipt_byte_size: bytes.size, receipt_sha256: sha256, output_characters: outputCharacters, truncated: outputCharacters > MAX_CAPTURE_BYTES };
+  await retryTerminalUpdate(context, update, call);
+  try { await unlink(context.context_path); } catch { /* receipt is authoritative; context cleanup is best effort */ }
+  return receipt;
+}
+
+export async function retryTerminalUpdate(context, update, call, { sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = {}) {
+  let attempts = 0;
+  let delay = 1_000;
+  for (;;) {
+    let result;
+    try { result = await call("update_command_run", update); } catch (error) { result = { ok: false, error: error instanceof Error ? error.message : String(error) }; }
+    if (result?.ok && !result.isError && result.data?.error == null && result.data?.accepted !== false) return result;
+    attempts += 1;
+    await writeJson(context.context_path, { ...context, terminal_update: { ...update, attempts, last_error: result?.error ?? result?.data?.error ?? "terminal_update_rejected", next_retry_at: new Date(Date.now() + delay).toISOString() } });
+    await sleep(delay);
+    delay = Math.min(delay * 2, 60_000);
+  }
+}
+
+export async function cmdRun(args) {
+  if (args[0] === "--worker") { await runWorker(args[1]); return; }
+  if (args[0] === "cancel") {
+    const result = await cancelRun(args[1] ?? "");
+    oneLine(result.receipt, false);
+    process.exitCode = result.exitCode;
+    return;
+  }
+  if (args[0] === "help" || args[0] === "--help") {
+    console.log("botbuddy run --session-id <id> --environment <local|preview|staging|production|none> [--timeout <sec>] [--rerun-reason <json>] -- <command> [args...]\nbotbuddy run cancel <run_id>");
+    return;
+  }
+  const result = await launchRun(args);
+  oneLine(result.receipt, Boolean(parseRunArgs(args).opts.json));
+  process.exitCode = result.exitCode;
+}