@botbuddy/cli 1.61.4 → 1.61.6

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.61.4",
-  "source_commit": "b6e939df36d913c84893c35c4f35a74cb8fb9675",
-  "source_sha256": "4b2c9b81b1e46f417dd3f1b58c19f6e03c4fbb6fa697a6b2ac2db0586551614b",
+  "release_version": "1.61.6",
+  "source_commit": "1e8d5f51d3f9be35c44e793551defaeaf8ae2d23",
+  "source_sha256": "0156e8ade4a62f2a6c4cb29d57fa0f5c23600ba264093198900c22e4c6fc0d68",
   "target": "darwin-arm64",
-  "sha256": "24fe172b82abb3ac4e59574516d614f1a35ec19b1fb2789793e4d877f8b0e526"
+  "sha256": "8bc316711530d7900ff4186b4eb114cf48ce255344d5d3436962c8d6bee46810"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.61.4",
-  "source_commit": "b6e939df36d913c84893c35c4f35a74cb8fb9675",
-  "source_sha256": "4b2c9b81b1e46f417dd3f1b58c19f6e03c4fbb6fa697a6b2ac2db0586551614b",
+  "release_version": "1.61.6",
+  "source_commit": "1e8d5f51d3f9be35c44e793551defaeaf8ae2d23",
+  "source_sha256": "0156e8ade4a62f2a6c4cb29d57fa0f5c23600ba264093198900c22e4c6fc0d68",
   "target": "linux-x64",
-  "sha256": "227d9145bedfb733e88e1456e2e8a9c989a12201b2c16427b2a7be2c27661bdf"
+  "sha256": "3bf5b7a6396da374f12abada7e42685ad8f783366c5c4de885da21d9749b257b"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.61.4",
-  "source_commit": "b6e939df36d913c84893c35c4f35a74cb8fb9675",
-  "source_sha256": "4b2c9b81b1e46f417dd3f1b58c19f6e03c4fbb6fa697a6b2ac2db0586551614b",
+  "release_version": "1.61.6",
+  "source_commit": "1e8d5f51d3f9be35c44e793551defaeaf8ae2d23",
+  "source_sha256": "0156e8ade4a62f2a6c4cb29d57fa0f5c23600ba264093198900c22e4c6fc0d68",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "24fe172b82abb3ac4e59574516d614f1a35ec19b1fb2789793e4d877f8b0e526",
+      "sha256": "8bc316711530d7900ff4186b4eb114cf48ce255344d5d3436962c8d6bee46810",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "227d9145bedfb733e88e1456e2e8a9c989a12201b2c16427b2a7be2c27661bdf",
+      "sha256": "3bf5b7a6396da374f12abada7e42685ad8f783366c5c4de885da21d9749b257b",
       "mode": "0755"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.61.4",
+  "version": "1.61.6",
   "description": "BotBuddy \u2014 Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/daemon/bootstrap.mjs

@@ -4,15 +4,18 @@
 // no local approval polling loop: host policy wakes only through the pushed
 // BOT-2324 raw wait condition, then this flow re-registers server-side.
 import { createHash } from "node:crypto";
+import { dirname } from "node:path";
 
 import { DAEMON_PRODUCTION_MCP_SERVER, enrollDaemonDeviceProfileFromBootstrapIdentity } from "./enrollment.mjs";
 import { installRemoteService, installedBinaryPath, stageRemoteDaemonRelease } from "./installer.mjs";
 import {
   createRemoteBootstrapIdentity,
   deliverDaemonProfileFromBootstrapIdentityOverSSH,
+  installDaemonRuntimeConfigOverSSH,
   inspectRemoteBootstrapIdentity,
   verifyRemoteServiceIdentity,
 } from "./profile-delivery.mjs";
+import { buildRuntimeConfig } from "./runtime-config.mjs";
 import { validateDaemonRelease } from "./release.mjs";
 import { renderLinuxUnit, renderMacDaemon } from "./service.mjs";
 
@@ -45,7 +48,7 @@ function exactObject(value, keys) {
 function checkedSpec(spec) {
   const keys = [
     "mode", "serverUrl", "sshHost", "serviceUser", "daemonBinary", "profilePath", "requestingHost",
-    "runtimeEngineId", "platform", "arch", "releaseRoot", "home", "config", "approvalTimeoutSeconds",
+    "runtimeEngineId", "platform", "arch", "releaseRoot", "home", "config", "hostPolicy", "approvalTimeoutSeconds",
   ];
   const optional = ["caller", "callerHarness", "callerTicket"];
   if (!spec || typeof spec !== "object" || Array.isArray(spec) ||
@@ -59,7 +62,11 @@ function checkedSpec(spec) {
     typeof spec.requestingHost !== "string" || !spec.requestingHost || Buffer.byteLength(spec.requestingHost, "utf8") > 80 ||
     typeof spec.runtimeEngineId !== "string" || !ENGINE_ID_RE.test(spec.runtimeEngineId) ||
     !["darwin", "linux"].includes(spec.platform) || typeof spec.arch !== "string" || !spec.arch ||
-    !validPath(spec.releaseRoot) || !validPath(spec.home) || !validPath(spec.config) ||
+    !validPath(spec.releaseRoot) || !validPath(spec.home) || !validPath(spec.config) || !spec.config.endsWith("/daemon.json") ||
+    dirname(spec.config) !== dirname(spec.profilePath) ||
+    !spec.hostPolicy || typeof spec.hostPolicy !== "object" || Array.isArray(spec.hostPolicy) ||
+    Object.keys(spec.hostPolicy).length !== 4 ||
+    !["machineId", "dockerEndpoint", "supabaseBinary", "dockerCLI"].every((key) => typeof spec.hostPolicy[key] === "string" && spec.hostPolicy[key]) ||
     !Number.isSafeInteger(spec.approvalTimeoutSeconds) || spec.approvalTimeoutSeconds < 1 || spec.approvalTimeoutSeconds > 3_600 ||
     optional.some((key) => spec[key] !== undefined && (typeof spec[key] !== "string" || !spec[key]))
   ) fail("daemon_bootstrap_spec_invalid");
@@ -215,12 +222,14 @@ export async function bootstrapFreshDaemon(input, {
   enroll = enrollDaemonDeviceProfileFromBootstrapIdentity,
   deliver = deliverDaemonProfileFromBootstrapIdentityOverSSH,
   installRemote = installRemoteService,
+  installRuntimeConfig = installDaemonRuntimeConfigOverSSH,
 } = {}) {
   const spec = checkedSpec(input);
   if (typeof registerHost !== "function" || typeof verifyRemoteIdentity !== "function" ||
       typeof createIdentity !== "function" || typeof inspectIdentity !== "function" ||
       typeof validateRelease !== "function" || typeof stageRemote !== "function" || typeof enroll !== "function" ||
       typeof deliver !== "function" || typeof installRemote !== "function" ||
+      typeof installRuntimeConfig !== "function" ||
       (awaitApproval !== null && typeof awaitApproval !== "function") ||
       (onApprovalRequired !== null && typeof onApprovalRequired !== "function") ||
       (resumeStore !== null && (typeof resumeStore !== "object" || typeof resumeStore.save !== "function" ||
@@ -355,6 +364,42 @@ export async function bootstrapFreshDaemon(input, {
     }
   }
 
+  let runtimeConfig;
+  try {
+    runtimeConfig = buildRuntimeConfig({
+      host_key: publicIdentity.hostKey,
+      state_dir: dirname(spec.config),
+      docker_endpoint: spec.hostPolicy.dockerEndpoint,
+      expected_engine_id: spec.runtimeEngineId,
+      machine_id: spec.hostPolicy.machineId,
+      supabase_binary: spec.hostPolicy.supabaseBinary,
+      docker_cli: spec.hostPolicy.dockerCLI,
+      host_credential_profile: spec.profilePath,
+      device_consent: true,
+      runtime_version: `go-daemon/${release.releaseVersion}`,
+      runtime_git_sha: release.sourceCommit,
+      runtime_protocol_version: 2,
+    });
+  } catch {
+    fail("daemon_bootstrap_runtime_config_invalid");
+  }
+  try {
+    const installed = await installRuntimeConfig({
+      config: JSON.stringify(runtimeConfig),
+      configPath: spec.config,
+      sshHost: spec.sshHost,
+      serviceUser: spec.serviceUser,
+      daemonBinary: trustedDaemonBinary,
+      profilePath: spec.profilePath,
+      expectedHostKey: publicIdentity.hostKey,
+      directInstall: remote.directInstall,
+    });
+    if (!installed || installed.installed !== true) fail("daemon_bootstrap_runtime_config_failed");
+  } catch (error) {
+    if (error instanceof DaemonBootstrapError) throw error;
+    fail("daemon_bootstrap_runtime_config_failed");
+  }
+
   const serviceSpec = {
     user: spec.serviceUser,
     home: spec.home,

package/src/daemon/commands.mjs

@@ -29,6 +29,7 @@ import {
   createRemoteBootstrapIdentity,
   deliverDaemonProfileFromBootstrapIdentityOverSSH,
   deliverDaemonProfileFromHelperIdentityOverSSH,
+  installDaemonRuntimeConfigOverSSH,
   inspectRemoteBootstrapIdentity,
   verifyRemoteHelperIdentity as verifyRemoteHelperIdentityOnTarget,
   verifyRemoteServiceIdentity,
@@ -285,6 +286,7 @@ export async function cmdDaemon(args, {
   verifyRuntime = checkRuntimeConfig,
   enroll = enrollDaemonDeviceProfileFromHelperIdentity,
   deliver = deliverDaemonProfileFromHelperIdentityOverSSH,
+  installRuntimeConfig = installDaemonRuntimeConfigOverSSH,
   verifyRemoteIdentity = verifyRemoteServiceIdentity,
   verifyRemoteHelperIdentity = verifyRemoteHelperIdentityOnTarget,
   bootstrap = bootstrapFreshDaemon,
@@ -332,6 +334,7 @@ export async function cmdDaemon(args, {
         },
         enroll: enrollBootstrap,
         deliver: deliverBootstrap,
+        installRuntimeConfig,
         installRemote,
         onApprovalRequired: ({ approval_url: approvalUrl, host_key: hostKey }) => {
           notice(`bb daemon bootstrap: owner approval required for ${hostKey}: ${approvalUrl}`);

package/src/daemon/profile-delivery.mjs

@@ -334,3 +334,32 @@ export async function deliverDaemonProfileFromBootstrapIdentityOverSSH({
     installFlag: "--install-profile-from-bootstrap-identity",
   });
 }
+
+// Runtime policy is public host metadata, never a credential. It is still
+// installed through the daemon's descriptor-pinned private root so a caller
+// cannot redirect it with a symlink or broaden a prior host's policy.
+export async function installDaemonRuntimeConfigOverSSH({
+  config,
+  configPath,
+  sshHost,
+  serviceUser,
+  daemonBinary,
+  profilePath,
+  expectedHostKey,
+  sshBin = "ssh",
+  spawnImpl = realSpawn,
+  env = process.env,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  directInstall = false,
+} = {}) {
+  safeInputs({ sshHost, serviceUser, daemonBinary, profilePath, expectedHostKey, sshBin, spawnImpl, env, timeoutMs, directInstall });
+  if (typeof config !== "string" || config.length === 0 || Buffer.byteLength(config, "utf8") > 64 * 1024 ||
+      typeof configPath !== "string" || !SAFE_ABSOLUTE_PATH.test(configPath) || !configPath.endsWith("/daemon.json")) throw invalid();
+  const command = remoteDaemonCommand({
+    serviceUser, daemonBinary, directInstall,
+    args: ["--install-runtime-config", "--config", configPath, "--profile", profilePath, "--expected-host-key", expectedHostKey],
+  });
+  const stdout = await fixedSsh({ sshHost, sshBin, spawnImpl, env, timeoutMs, command, stdin: Buffer.from(config, "utf8") });
+  if (!stdout.equals(Buffer.from('{"installed":true}\n'))) throw failed();
+  return { installed: true };
+}

package/src/wait-result.mjs

@@ -0,0 +1,142 @@
+// BOT-1688 — observation of an existing wait, independent of condition matching.
+// No registration, subscription, finalization or acknowledgement belongs here.
+import { constants } from "node:fs";
+import { open, realpath } from "node:fs/promises";
+import { isDeepStrictEqual } from "node:util";
+import { harnessSessionIdFromEnv, readAgentState } from "./agent-state.mjs";
+import { readAgentSessionTokenEnv } from "./agent-key.mjs";
+import { WaitCheckpointError } from "./wait-checkpoint.mjs";
+
+const MAX_ARTIFACT_BYTES = 256 * 1024;
+const MAX_RECEIPT_BYTES = 64 * 1024;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const TERMINAL_OUTCOMES = new Set(["matched", "timeout", "error", "superseded", "lease_lost", "abandoned", "cancelled"]);
+
+// Persisted != delivered. Await the stream callback before exiting, including
+// when a bounded receipt is larger than the pipe's immediately writable space.
+export function writeWaitReceipt(receipt, output = process.stdout) {
+  const line = `${JSON.stringify(receipt)}\n`;
+  return new Promise((resolve, reject) => {
+    const failed = (error) => reject(error);
+    output.once("error", failed);
+    try {
+      output.write(line, (error) => {
+        if (error) reject(error);
+        else { output.off("error", failed); resolve(); }
+      });
+    } catch (error) { output.off("error", failed); reject(error); }
+  });
+}
+
+export function waitObserverId(env = process.env) {
+  const id = harnessSessionIdFromEnv(env);
+  if (id) return id;
+  if (env.CLAUDE_CODE_CHILD_SESSION === "1") return null;
+  const thread = env.CODEX_THREAD_ID;
+  return typeof thread === "string" && UUID.test(thread) ? thread.toLowerCase() : null;
+}
+
+export function waitCompletionState(checkpoint) {
+  if (checkpoint.status === "acknowledged") return "consumed";
+  if (checkpoint.status === "cancelled") return "cancelled";
+  if (checkpoint.status === "terminal") return checkpoint.terminal_receipt ? "receipt_available" : "observation_gap";
+  return ["preparing", "armed", "interrupted"].includes(checkpoint.status) ? "waiting" : "invalid";
+}
+
+export async function assertWaitObserver(checkpoint, { cwd = process.cwd(), env = process.env, requirePrincipal = false } = {}) {
+  let same = false;
+  try { same = await realpath(checkpoint.worktree) === await realpath(cwd); } catch { /* fail closed */ }
+  if (!same) throw new WaitCheckpointError("wait_resume_identity_mismatch", "saved wait belongs to a different worktree");
+  const observer = waitObserverId(env);
+  if (checkpoint.observer_harness_id && checkpoint.observer_harness_id !== observer) {
+    throw new WaitCheckpointError("wait_resume_identity_mismatch", "saved wait belongs to a different harness task");
+  }
+  // Local files are OS-user protected. For an authenticated result, also require
+  // the same cached agent/tenant; never mint an identity to read a local receipt.
+  if (requirePrincipal && (checkpoint.agent_id || checkpoint.tenant_id)) {
+    const state = await readAgentState(cwd);
+    const token = readAgentSessionTokenEnv(env);
+    if (!state || (token && token !== state.agent_session_token) ||
+        state.agent_id !== checkpoint.agent_id || state.tenant !== checkpoint.tenant_id ||
+        (observer && state.harness_session_id && observer !== state.harness_session_id)) {
+      throw new WaitCheckpointError("wait_resume_identity_mismatch", "result requires this worktree's original agent and tenant; use named resume with fresh credentials for recovery");
+    }
+  }
+}
+
+async function receiptFromArtifact(path) {
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > MAX_ARTIFACT_BYTES) throw new Error("unbounded artifact");
+    const buffer = Buffer.alloc(MAX_ARTIFACT_BYTES + 1);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    if (bytesRead > MAX_ARTIFACT_BYTES) throw new Error("unbounded artifact");
+    const receipts = [];
+    for (const line of buffer.subarray(0, bytesRead).toString("utf8").split(/\r?\n/)) {
+      if (!line.trimStart().startsWith("{")) continue;
+      let value;
+      try { value = JSON.parse(line); } catch { continue; }
+      if (value?.schema_version === 1 && typeof value.outcome === "string") receipts.push(value);
+    }
+    if (receipts.length !== 1) throw new Error("expected exactly one receipt");
+    return receipts[0];
+  } catch {
+    // Never echo arbitrary artifact contents (which may include credentials).
+    throw new WaitCheckpointError("wait_observation_gap", "completion artifact must contain exactly one bounded terminal receipt");
+  } finally { await handle?.close(); }
+}
+
+export async function readWaitResult(store, id, { cwd, env, fromFile = null, exitCode = null } = {}) {
+  // An explicitly named artifact identifies a cloud wait, not "the newest"
+  // checkpoint. Read it once, only after the caller awaited the original exit.
+  const observed = fromFile == null ? null : await receiptFromArtifact(fromFile);
+  if (id == null) {
+    const cloudId = observed?.wait_session_id;
+    if (typeof cloudId !== "string" || !cloudId) {
+      throw new WaitCheckpointError("wait_observation_gap", "artifact has no cloud wait identity; select its exact local_wait_id explicitly");
+    }
+    const matches = [];
+    let offset = 0;
+    do {
+      const page = await store.list({ includeInactive: true, offset });
+      for (const item of page.items) if (item.cloud_wait_session_id === cloudId) matches.push(item.local_wait_id);
+      offset = page.next_offset;
+    } while (offset != null);
+    if (matches.length !== 1) {
+      throw new WaitCheckpointError("wait_observation_gap", "artifact must identify exactly one checkpoint in this worktree");
+    }
+    [id] = matches;
+  }
+  let checkpoint = await store.read(id);
+  await assertWaitObserver(checkpoint, { cwd, env, requirePrincipal: true });
+  const state = waitCompletionState(checkpoint);
+  if (state !== "receipt_available") {
+    throw new WaitCheckpointError(state === "consumed" ? "wait_result_consumed" : "wait_result_unavailable", `saved wait ${id}: ${state}; no new wait was started`);
+  }
+  // Frame-time persistence may precede the original owner's stdout and exit.
+  // Its process-instance fence, not a file or PID sighting, decides ownership.
+  const fence = await store.acquireFence(id);
+  try {
+    checkpoint = await store.read(id);
+    await assertWaitObserver(checkpoint, { cwd, env, requirePrincipal: true });
+    if (waitCompletionState(checkpoint) !== "receipt_available") {
+      throw new WaitCheckpointError("wait_result_unavailable", "saved wait changed before observation");
+    }
+    const receipt = checkpoint.terminal_receipt;
+    if (!receipt || Array.isArray(receipt) || receipt.schema_version !== 1 || !TERMINAL_OUTCOMES.has(receipt.outcome) ||
+        Buffer.byteLength(JSON.stringify(receipt)) > MAX_RECEIPT_BYTES ||
+        !Number.isInteger(checkpoint.exit_code) || checkpoint.exit_code < 0 || checkpoint.exit_code > 255 ||
+        (receipt.wait_session_id !== undefined && receipt.wait_session_id !== (checkpoint.cloud_wait_session_id ?? null)) ||
+        (receipt.principal && checkpoint.agent_id && receipt.principal.agent_id !== checkpoint.agent_id) ||
+        (receipt.principal && checkpoint.tenant_id && receipt.principal.tenant_id !== checkpoint.tenant_id)) {
+      throw new WaitCheckpointError("wait_observation_gap", "saved terminal receipt does not match its wait identity");
+    }
+    if (fromFile != null && (!Number.isInteger(exitCode) || exitCode !== checkpoint.exit_code ||
+        !isDeepStrictEqual(observed, receipt))) {
+      throw new WaitCheckpointError("wait_observation_gap", "original command exit or redirected receipt differs from the selected durable result");
+    }
+    return { receipt, exitCode: checkpoint.exit_code };
+  } finally { await fence.release(); }
+}

package/src/wait.mjs

@@ -4,8 +4,8 @@
 // Park on a set of conditions (a lock coming free, a chat reply, a build
 // finishing, a plain deadline) and wake EXACTLY ONCE with one machine-readable
 // JSON receipt on stdout. Zero polling, zero tokens spent while waiting: the
-// process blocks on a pushed SSE stream and the agent harness (Claude Code
-// `run_in_background`, Codex background exec) is re-invoked when it exits.
+// process blocks on a pushed SSE stream. The owning harness retains its pending
+// result; process exit is not proof that the agent consumed the receipt.
 //
 // Dependency-free (Node >= 20 stdlib only). All wait semantics live in
 // ./wait-core.mjs; this file is just argv + a real `connect()` + I/O.
@@ -26,6 +26,7 @@ import { SETUP_BLOCK } from "./setup-block.mjs";
 import { createWaitCheckpointStore, WaitCheckpointError } from "./wait-checkpoint.mjs";
 import { realpath } from "node:fs/promises";
 import { deepLinkNotice, safeWebUrl } from "./deep-link.mjs";
+import { assertWaitObserver, readWaitResult, waitCompletionState, waitObserverId, writeWaitReceipt } from "./wait-result.mjs";
 
 // A protocol is deliberately distinct from package semver: compatible pinned
 // clients keep working until the server raises this minimum, while a stale
@@ -181,6 +182,9 @@ OPTIONS
   --session-id <uuid>   advanced attribution override; normal worktrees derive it automatically.
   --help                show this help
   resume <local_wait_id>       recover one explicitly named saved wait
+  result [<local_wait_id>]     read its terminal receipt without rearming or acknowledging
+    [--from-file <path> --exit-code <n>]
+                              validate redirected output AFTER the original command exits
   cancel <local_wait_id>       explicitly stop one saved wait
   acknowledge <local_wait_id>  mark one saved terminal receipt read
 
@@ -933,7 +937,7 @@ function emit(receipt, { versioned = false, maxBytes = null } = {}) {
   const bounded = Number.isSafeInteger(maxBytes) && maxBytes >= MIN_RECEIPT_MAX_BYTES
     ? truncateReceipt(enriched, maxBytes)
     : enriched;
-  process.stdout.write(JSON.stringify(bounded) + "\n");
+  return writeWaitReceipt(bounded);
 }
 
 // BOT-1590: canonical one-line recoveries for every setup/auth/parameter error.
@@ -1081,12 +1085,15 @@ function inventoryEntry(checkpoint) {
   const pendingAcknowledgement = checkpoint.status === "acknowledged" && checkpoint.cloud_ack_pending === true;
   return {
     local_wait_id: id,
+    wait_session_id: checkpoint.cloud_wait_session_id ?? null,
     status: checkpoint.status,
+    completion_state: waitCompletionState(checkpoint),
     conditions: checkpoint.conditions?.map((c) => ({ condition_id: c.id, type: c.type })) ?? [],
     ticket: checkpoint.ticket ?? null,
     created_at: checkpoint.created_at ?? null,
     deadline_at: checkpoint.deadline_at ?? null,
     receipt_available: terminal && checkpoint.terminal_receipt != null,
+    result_argv: terminal ? ["wait", "result", id] : null,
     recovery_argv: pendingCancellation
       ? ["wait", "cancel", id]
       : pendingAcknowledgement ? ["wait", "acknowledge", id] : ["wait", "resume", id],
@@ -1105,13 +1112,13 @@ async function inspectSavedWaits(argv = []) {
   // Never let a non-interactive agent accidentally acquire an owner or consume
   // a result.  The inventory deliberately omits receipt bodies and shell text.
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
-    process.stdout.write(`${JSON.stringify({
+    await writeWaitReceipt({
       schema_version: 1,
       outcome: "saved_waits",
       waits: inventory.items.map(inventoryEntry),
       has_more: inventory.has_more,
       ...(inventory.next_offset != null ? { next_offset: inventory.next_offset, next_page_argv: ["wait", "--offset", String(inventory.next_offset)] } : {}),
-    })}\n`);
+    });
     process.exit(EXIT.MATCHED);
   }
   if (inventory.items.length === 0) {
@@ -1336,6 +1343,8 @@ async function resumeSavedWait(id) {
   let checkpoint;
   try { checkpoint = await store.read(id); }
   catch (error) { return emitSavedWaitError(error); }
+  try { await assertWaitObserver(checkpoint); }
+  catch (error) { return emitSavedWaitError(error); }
   if (!(await sameWorktree(checkpoint.worktree, process.cwd()))) {
     return emitSavedWaitError(new WaitCheckpointError("wait_resume_identity_mismatch", "saved wait belongs to a different worktree"));
   }
@@ -1355,7 +1364,7 @@ async function resumeSavedWait(id) {
       await fence?.release();
     }
     writeLeaseLostNotice(checkpoint.terminal_receipt);
-    process.stdout.write(`${JSON.stringify(checkpoint.terminal_receipt)}\n`);
+    await writeWaitReceipt(checkpoint.terminal_receipt);
     process.exit(Number.isInteger(checkpoint.exit_code) ? checkpoint.exit_code : EXIT.INTERNAL);
   }
   if (["cancelled", "acknowledged"].includes(checkpoint.status)) {
@@ -1382,18 +1391,18 @@ async function sameWorktree(first, second) {
   catch { return false; }
 }
 
-function emitSavedWaitError(error) {
+async function emitSavedWaitError(error) {
   const code = error?.code ?? "wait_checkpoint_invalid";
   const exitCode = code === "wait_checkpoint_write_failed" ? EXIT.INTERNAL : EXIT.INVALID;
   process.stderr.write(`bb-wait: ${error?.message ?? code}\n`);
-  process.stdout.write(`${JSON.stringify({
+  await writeWaitReceipt({
     schema_version: 1,
     outcome: "error",
     error: code,
     ...(error?.localWaitId ? { local_wait_id: error.localWaitId } : {}),
     ...(Array.isArray(error?.recoveryArgv) ? { recovery_argv: error.recoveryArgv } : {}),
     ...(typeof error?.recovery === "string" ? { recovery: error.recovery } : {}),
-  })}\n`);
+  });
   process.exit(exitCode);
 }
 
@@ -1413,6 +1422,7 @@ async function cancelSavedWait(id) {
   try {
     const store = checkpointStore();
     let current = await store.read(id);
+    await assertWaitObserver(current);
     if (current.status === "terminal" || current.status === "acknowledged") {
       const conflict = new WaitCheckpointError(
         "wait_not_cancellable",
@@ -1518,10 +1528,10 @@ async function cancelSavedWait(id) {
     } finally {
       await fence.release();
     }
-    process.stdout.write(`${JSON.stringify({
+    await writeWaitReceipt({
       schema_version: 1, outcome: "cancelled", local_wait_id: id,
       ...(current.cloud_cancel_pending ? { cloud_cancel_pending: true } : {}),
-    })}\n`);
+    });
     process.exit(EXIT.MATCHED);
   } catch (error) { return emitSavedWaitError(error); }
 }
@@ -1535,6 +1545,7 @@ async function acknowledgeSavedWait(id) {
     // until the same process-instance fence used by resume proves ownership.
     fence = await store.acquireFence(id);
     let checkpoint = await store.read(id);
+    await assertWaitObserver(checkpoint, { requirePrincipal: Boolean(checkpoint.observer_harness_id) });
     if (checkpoint.status === "terminal") checkpoint = await flushPendingFinalization(store, checkpoint);
     checkpoint = await store.acknowledge(id, {
       cloudAckPending: Boolean(checkpoint.cloud_wait_session_id),
@@ -1542,10 +1553,10 @@ async function acknowledgeSavedWait(id) {
     if (checkpoint.cloud_wait_session_id) {
       checkpoint = await flushPendingAcknowledgement(store, checkpoint);
     }
-    process.stdout.write(`${JSON.stringify({
+    await writeWaitReceipt({
       schema_version: 1, outcome: "acknowledged", local_wait_id: id,
       ...(checkpoint.cloud_ack_pending ? { cloud_ack_pending: true } : {}),
-    })}\n`);
+    });
     await fence.release();
     fence = null;
     process.exit(EXIT.MATCHED);
@@ -1557,6 +1568,22 @@ async function acknowledgeSavedWait(id) {
 
 export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   if (argv.length === 0 || argv[0] === "--offset") return inspectSavedWaits(argv);
+  if (argv[0] === "result") {
+    try {
+      const args = argv.slice(1);
+      const id = args[0] && !args[0].startsWith("--") ? args.shift() : null;
+      const rest = args;
+      if ((!id && !rest.length) || (rest.length !== 0 && (rest.length !== 4 || rest[0] !== "--from-file" ||
+          !rest[1] || rest[2] !== "--exit-code" || !/^\d{1,3}$/.test(rest[3]) || Number(rest[3]) > 255))) {
+        throw new WaitCheckpointError("wait_observation_gap", "usage: bb wait result [<local_wait_id>] [--from-file <path> --exit-code <n>]; await the original command first");
+      }
+      const result = await readWaitResult(checkpointStore(), id, {
+        fromFile: rest[1] ?? null, exitCode: rest.length ? Number(rest[3]) : null,
+      });
+      await writeWaitReceipt(result.receipt);
+      process.exit(result.exitCode);
+    } catch (error) { return emitSavedWaitError(error); }
+  }
   // BOT-1701 (AC-6): one stderr nudge for a tier-3 legacy alias (flag, env, or a
   // bb_agent_ token value), emitted BEFORE any subcommand dispatch so the
   // credentialed recovery actions (resume/cancel/acknowledge) warn too (Codex R7).
@@ -1592,7 +1619,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       `botbuddy wait: ${opts.retiredFlag} is retired — run bb wait from a configured worktree and it restores its session automatically. `
         + "If setup is needed, run bb setup, then retry the same wait.\n",
     );
-    emitReceipt({
+    await emitReceipt({
       schema_version: 1,
       outcome: "error",
       error: "unknown_option",
@@ -1603,18 +1630,18 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   }
   if (opts.unknown) {
     process.stderr.write(`bb-wait: unknown option ${opts.unknown}\n`);
-    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_arguments", option: opts.unknown });
+    await emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_arguments", option: opts.unknown });
     process.exit(EXIT.INVALID);
   }
   if (opts.missing) {
     process.stderr.write(`bb-wait: option ${opts.missing} requires a value\n`);
-    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_arguments", option: opts.missing });
+    await emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_arguments", option: opts.missing });
     process.exit(EXIT.INVALID);
   }
   if ((opts.resumeLocalWait != null || opts.deadlineAt != null) &&
       (recoveryLocalWaitId == null || opts.resumeLocalWait !== recoveryLocalWaitId)) {
     process.stderr.write("bb-wait: saved wait recovery options are internal; use bb wait resume <local_wait_id>\n");
-    emitReceipt({
+    await emitReceipt({
       schema_version: 1,
       outcome: "error",
       error: "wait_not_resumable",
@@ -1624,7 +1651,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   }
   if (opts.deadlineAt != null && !opts.resumeLocalWait) {
     process.stderr.write("bb-wait: --deadline-at is reserved for saved wait recovery\n");
-    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_arguments", option: "--deadline-at" });
+    await emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_arguments", option: "--deadline-at" });
     process.exit(EXIT.INVALID);
   }
 
@@ -1635,7 +1662,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
     const since = normalizeSince(opts.since);
     if (since.kind !== "ok") {
       process.stderr.write("bb-wait: --since must be a non-negative signal sequence <= 9007199254740991\n");
-      emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_since", cursor: opts.since });
+      await emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_since", cursor: opts.since });
       process.exit(EXIT.INVALID);
     }
     opts.since = since.value;
@@ -1645,7 +1672,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   if (errors.length > 0) {
     for (const e of errors) process.stderr.write(`bb-wait: invalid condition '${e.spec}': ${e.message}\n`);
     process.stderr.write(`bb-wait: ${RECOVERY.conditions}\n`);
-    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_conditions", errors, recovery: RECOVERY.conditions });
+    await emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_conditions", errors, recovery: RECOVERY.conditions });
     // BOT-1593: condition_types is [] on a grammar failure (the parsed set is
     // partial/empty and is caller data regardless). BOT-2467: instead, each failed
     // spec is described by its attempted TYPE and a parse_error category — never
@@ -1656,13 +1683,13 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
 
   if (!Number.isFinite(opts.timeout) || opts.timeout <= 0) {
     process.stderr.write("bb-wait: --timeout must be a positive number of seconds\n");
-    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_timeout" });
+    await emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_timeout" });
     process.exit(EXIT.INVALID);
   }
   if (!Number.isSafeInteger(opts.receiptMaxBytes) || opts.receiptMaxBytes < MIN_RECEIPT_MAX_BYTES ||
       opts.receiptMaxBytes > MAX_RECEIPT_MAX_BYTES) {
     process.stderr.write(`bb-wait: --receipt-max-bytes must be an integer from ${MIN_RECEIPT_MAX_BYTES} through ${MAX_RECEIPT_MAX_BYTES}\n`);
-    emitReceipt({
+    await emitReceipt({
       schema_version: 1, outcome: "error", error: "invalid_receipt_max_bytes",
       minimum: MIN_RECEIPT_MAX_BYTES, maximum: MAX_RECEIPT_MAX_BYTES,
     });
@@ -1674,7 +1701,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   });
   if (shortRefusal) {
     process.stderr.write(`bb-wait: --timeout ${opts.timeout} is under the ${MIN_WAIT_TIMEOUT_SEC} s floor — ${shortRefusal.recovery}\n`);
-    emitReceipt({ schema_version: 1, outcome: "error", ...shortRefusal });
+    await emitReceipt({ schema_version: 1, outcome: "error", ...shortRefusal });
     process.exit(EXIT.INVALID);
   }
   if (opts.timeout < MIN_WAIT_TIMEOUT_SEC && !conditions.every((condition) => condition.type === "timer") && !opts.resumeLocalWait) {
@@ -1683,7 +1710,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   const timeoutSec = Math.min(opts.timeout, MAX_WAIT_TIMEOUT_SEC); // BOT-2400: 72 h hard cap
   const deadlineMs = opts.deadlineAt == null ? Date.now() + timeoutSec * 1000 : Date.parse(opts.deadlineAt);
   if (!Number.isFinite(deadlineMs)) {
-    emitReceipt({ schema_version: 1, outcome: "error", error: "wait_checkpoint_invalid" });
+    await emitReceipt({ schema_version: 1, outcome: "error", error: "wait_checkpoint_invalid" });
     process.exit(EXIT.INVALID);
   }
 
@@ -1735,6 +1762,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
         receipt_max_bytes: opts.receiptMaxBytes,
         relay_url: relayUrl,
         worktree: process.cwd(),
+        observer_harness_id: waitObserverId(),
       });
     }
     // A live process retains this fence until exit. The file records a PID and
@@ -1780,7 +1808,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
         ? "run from a configured project worktree, then run `bb setup` and retry"
         : "run `bb setup` and retry";
       process.stderr.write(`botbuddy wait: ${error?.message ?? error}; ${recovery}\n`);
-      emitReceipt({ schema_version: 1, outcome: "error", error: code, recovery });
+      await emitReceipt({ schema_version: 1, outcome: "error", error: code, recovery });
       await reportSetupError(opts, { error: code, exitCode: EXIT.AUTH, conditions });
       process.exit(EXIT.AUTH);
     }
@@ -1794,13 +1822,13 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   if (needsRelay && opts.sessionToken) {
     if (!SESSION_TOKEN_RE.test(opts.sessionToken)) {
       process.stderr.write(`botbuddy wait: BOTBUDDY_AGENT_SESSION_TOKEN must match bb_sess_<64 hex> (bb_agent_ is a legacy prefix); ${RECOVERY.sessionToken}\n`);
-      emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_token", recovery: RECOVERY.sessionToken });
+      await emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_token", recovery: RECOVERY.sessionToken });
       await reportSetupError(opts, { error: "invalid_session_token", exitCode: EXIT.INVALID, conditions });
       process.exit(EXIT.INVALID);
     }
     if (opts.token && opts.token !== opts.sessionToken) {
       process.stderr.write(`botbuddy wait: --token conflicts with $BOTBUDDY_AGENT_SESSION_TOKEN; ${RECOVERY.sessionTokenConflict}\n`);
-      emitReceipt({ schema_version: 1, outcome: "error", error: "session_token_conflict", recovery: RECOVERY.sessionTokenConflict });
+      await emitReceipt({ schema_version: 1, outcome: "error", error: "session_token_conflict", recovery: RECOVERY.sessionTokenConflict });
       await reportSetupError(opts, { error: "session_token_conflict", exitCode: EXIT.INVALID, conditions });
       process.exit(EXIT.INVALID);
     }
@@ -1813,7 +1841,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
     process.stderr.write(
       `botbuddy wait: a relay wait requires the per-session agent token — ${RECOVERY.sessionToken}, then: botbuddy wait '<condition>'\n`,
     );
-    emitReceipt({
+    await emitReceipt({
       schema_version: 1,
       outcome: "error",
       error: "session_token_required",
@@ -1950,7 +1978,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
             cloud_cancel_error: null,
           } : {}),
         });
-        emitReceipt(recovered, { versioned: true });
+        await emitReceipt(recovered, { versioned: true });
         process.exit(exitForRecoveredOutcome(recovered));
       }
       // BOT-2468: the wait's dashboard deeplink, once, at arm time (and again on
@@ -2038,13 +2066,13 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       });
       if (hasClaim && waitSessionId == null) {
         process.stderr.write("bb-wait: claim=true registration returned no wait_session_id; refusing to arm an unmatchable claim wait\n");
-        emitReceipt({ schema_version: 1, outcome: "error", error: "claim_registration_failed" });
+        await emitReceipt({ schema_version: 1, outcome: "error", error: "claim_registration_failed" });
         process.exit(EXIT.INTERNAL);
       }
     } catch (err) {
       if (err && err.clientOutdated) {
         process.stderr.write(`botbuddy wait: client protocol is no longer supported — upgrade with: ${err.upgradeCommand}\n`);
-        emitReceipt({
+        await emitReceipt({
           schema_version: 1,
           outcome: "error",
           error: err.errorCode,
@@ -2061,7 +2089,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
           process.stderr.write(
             "botbuddy wait: this worktree needs a session; run bb setup, then retry the same wait\n",
           );
-          emitReceipt({
+          await emitReceipt({
             schema_version: 1,
             outcome: "error",
             error: "client_key_cannot_wait",
@@ -2083,7 +2111,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
           process.stderr.write(
             `botbuddy wait: ${cause}; run bb setup, then retry the same wait\n`,
           );
-          emitReceipt(withPrincipalReceipt({
+          await emitReceipt(withPrincipalReceipt({
             schema_version: 1,
             outcome: "error",
             error: err.errorCode,
@@ -2098,7 +2126,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
         process.stderr.write(
           `botbuddy wait: session rejected (${err.errorCode || "unauthorized"}) — run bb setup, then retry the same wait\n`,
         );
-        emitReceipt(withPrincipalReceipt({
+        await emitReceipt(withPrincipalReceipt({
           schema_version: 1,
           outcome: "error",
           error: err.errorCode || "unauthorized",
@@ -2111,7 +2139,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       }
       if (err && err.cap) {
         process.stderr.write(`bb-wait: too many active waits for this agent — ${err.message}\n`);
-        emitReceipt({
+        await emitReceipt({
           schema_version: 1,
           outcome: "error",
           error: err.errorCode || "wait_session_cap_exceeded",
@@ -2133,7 +2161,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
           ? "the Linear issue belongs to a different Linear workspace than this tenant"
           : "retry once Linear is reachable";
         process.stderr.write(`bb-wait: unblocked:${err.ticket ?? "?"} cannot register — ${reason}; ${fix}\n`);
-        emitReceipt({
+        await emitReceipt({
           schema_version: 1,
           outcome: "error",
           error: err.errorCode,
@@ -2155,7 +2183,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
           }
         }
         process.stderr.write(`bb-wait: invalid condition (${err.errorCode}) — ${err.message}\n`);
-        emitReceipt({
+        await emitReceipt({
           schema_version: 1,
           outcome: "error",
           error: err.errorCode,
@@ -2166,20 +2194,20 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       }
       if (err && err.initialEval) {
         process.stderr.write(`bb-wait: initial wait evaluation failed (${err.errorCode}) — ${err.detail}\n`);
-        emitReceipt({ schema_version: 1, outcome: "error", error: err.errorCode, detail: String(err.detail) });
+        await emitReceipt({ schema_version: 1, outcome: "error", error: err.errorCode, detail: String(err.detail) });
         process.exit(EXIT.INTERNAL);
       }
       if (err instanceof WaitCheckpointError) return emitSavedWaitError(err);
       if (hasClaim) {
         process.stderr.write(`bb-wait: claim=true wait-session registration failed (failing closed, not arming untracked): ${err && err.message || err}\n`);
-        emitReceipt({ schema_version: 1, outcome: "error", error: "claim_registration_failed" });
+        await emitReceipt({ schema_version: 1, outcome: "error", error: "claim_registration_failed" });
         process.exit(EXIT.INTERNAL);
       }
       // BOT-1338/1608: every non-timer wait is a relay-tracked, session-token wait.
       // If registration did not succeed, neither the server nor this client has
       // verified the session's tenant, so there is no safe untracked fallback.
       process.stderr.write(`bb-wait: wait-session registration failed (failing closed, not arming untracked): ${err && err.message || err}\n`);
-      emitReceipt(withPrincipalReceipt(
+      await emitReceipt(withPrincipalReceipt(
         { schema_version: 1, outcome: "error", error: "register_failed", detail: String(err && err.message || err) },
         null,
         { sessionTenant: sessionTenant ?? null, agentId: null },
@@ -2267,7 +2295,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
         status: "interrupted",
         safe_cursor: terminalReceipt.next_cursor ?? checkpoint.safe_cursor ?? null,
       });
-      emitReceipt(terminalReceipt, { versioned: true });
+      await emitReceipt(terminalReceipt, { versioned: true });
       process.exit(exitCode);
     }
     // Receipt first, stdout second, cloud finalization last. A killed harness can
@@ -2281,7 +2309,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
         cloud_finalize_pending: Boolean(waitSessionId && !SERVER_ENDED_OUTCOMES.has(terminalReceipt.outcome)),
       });
     }
-    emitReceipt(terminalReceipt, { versioned: true });
+    await emitReceipt(terminalReceipt, { versioned: true });
     // BOT-1228: a `superseded` outcome means an external actor already terminalized
     // this wait_session server-side (reconcile_waits_to_canonical → abandoned, with
     // ended_at/updated_at stamped). Skip the client finalize: the row is already
@@ -2314,7 +2342,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
     });
     process.stderr.write(`bb-wait: ${err && err.stack || err}\n`);
     // Receipt first, stdout second, cloud finalization last — as on the normal path.
-    emitReceipt(settled.receipt, { versioned: true });
+    await emitReceipt(settled.receipt, { versioned: true });
     await settled.finalizeCloud();
     process.exit(settled.exitCode);
   }