fix: require typed background terminal receipts

docs/research/WEB_TERMINAL_RECEIPT_TYPES_2026-10-07.md

@@ -0,0 +1,18 @@
+# Typed background terminal receipts
+
+- Status: validated source and regression evidence
+- Created / verified: 2026-10-07
+- Source: origin/main at 3cb2ecfe1bfbb98252651885311d309f83749428
+- Issue: [#702](https://github.com/openpi-dev/openpi/issues/702)
+- Supersedes: none
+
+## Verified facts
+
+Array-valued failed, killed and timed_out statuses were admitted by coercion and misreported as returned. Literal process statuses are now required; malformed receipts retain unknown process state independently of a successful tool return. Exit codes require safe integers.
+
+## Verification boundary
+
+Eight evidence tests pass after the new regression failed on baseline. Valid completion, failure, cancellation, timeout and running outcomes remain distinct.
+
+Full repository validation results and CI are recorded on the linked PR. Local
+Windows failures are retained separately and are not reported as passing.

tests/web/evidence.test.ts

@@ -216,3 +216,49 @@ test("successful foreground completion does not invent an exit code or complete
     "unknown",
   );
 });
+
+test("background process outcomes require literal status identities and integral exit codes", () => {
+  for (const status of [
+    ["done"],
+    ["failed"],
+    ["killed"],
+    ["timed_out"],
+    null,
+    {},
+    1,
+  ]) {
+    const evidence = projectToolEvidence(call("bg_status"), {
+      content: "status",
+      isError: false,
+      details: { status, exitCode: 7, signal: "SIGTERM" },
+    });
+    assert.equal(evidence.state, "returned");
+    assert.equal(evidence.processState, "unknown");
+    assert.equal(evidence.exitCode, undefined);
+    assert.equal(evidence.signal, undefined);
+  }
+  for (const [status, expected] of [
+    ["done", "returned"],
+    ["failed", "failed"],
+    ["killed", "cancelled"],
+    ["timed_out", "timed_out"],
+    ["running", "running"],
+  ]) {
+    const evidence = projectToolEvidence(call("bg_status"), {
+      content: "status",
+      isError: false,
+      details: { status, exitCode: 7 },
+    });
+    assert.equal(evidence.processState, expected);
+    assert.equal(evidence.exitCode, status === "running" ? undefined : 7);
+  }
+  for (const exitCode of [0.5, Number.MAX_SAFE_INTEGER + 1, Infinity, NaN]) {
+    assert.equal(
+      projectToolEvidence(call("bg_status"), {
+        content: "status",
+        details: { status: "failed", exitCode },
+      }).exitCode,
+      undefined,
+    );
+  }
+});

web/protocol/evidence.ts

@@ -76,10 +76,10 @@ function terminalOutcome(name: string, result?: WebLiveMessage) {
   if (name.startsWith("bg_")) {
     const status = details.status;
     if (status === "running") return { state: "running" as const };
-    if (["done", "failed", "killed", "timed_out"].includes(String(status))) {
+    if (typeof status === "string" && ["done", "failed", "killed", "timed_out"].includes(status)) {
       return {
         state: status === "killed" ? "cancelled" as const : status === "timed_out" ? "timed_out" as const : status === "failed" ? "failed" as const : "returned" as const,
-        exitCode: typeof details.exitCode === "number" ? details.exitCode : undefined,
+        exitCode: typeof details.exitCode === "number" && Number.isSafeInteger(details.exitCode) ? details.exitCode : undefined,
         signal: typeof details.signal === "string" ? evidenceText(details.signal).text : undefined,
       };
     }