@inflexa-ai/harness 0.42.2 → 0.43.1

package/dist/sandbox/k8s-client.d.ts

@@ -1,8 +1,9 @@
 /**
  * K8s-backed `createSandbox` / `teardown` / `isAlive`.
  *
- * Launches a sandbox Job with `CORTEX_BASE_URL` and `SANDBOX_CALLBACK_SECRET`
- * env vars; pod IP + port 8765 are the host/port Cortex POSTs `/exec` to.
+ * Launches a sandbox Job; pod IP + port 8765 are the host/port the host POSTs
+ * `/exec` to and polls. The pod initiates nothing: its confinement is a
+ * cluster-side NetworkPolicy, not an in-pod firewall.
  * Storage is wired via the shared session PVC: a flat read-only `volumeMount`
  * of the analysis tree at `/{resourceId}` plus a nested read-write mount of the
  * step's artifact dir, with the lib/ref stores mounted read-only at `/mnt/libs`
@@ -17,19 +18,12 @@ import { ResultAsync } from "neverthrow";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type SandboxError } from "./sandbox-error.js";
 import type { SpawnSession } from "../auth/types.js";
-import type { FarmSource, ManagedSandbox, SandboxIdentity, SandboxLabels, SandboxLiveness, SandboxRef, SandboxSpec, SandboxTransport, ToolchainSource } from "./types.js";
+import type { FarmSource, ManagedSandbox, SandboxIdentity, SandboxLabels, SandboxLiveness, SandboxRef, SandboxSpec, ToolchainSource } from "./types.js";
 import type { Logger } from "../lib/logger.js";
 export interface K8sClientConfig {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     image: string;
-    cortexBaseUrl: string;
-    /**
-     * Result transport, threaded to the pod as `SANDBOX_TRANSPORT`. Poll-mode
-     * confinement on K8s is a cluster-side NetworkPolicy, not an in-pod firewall.
-     * Defaults to `poll`.
-     */
-    transport?: SandboxTransport;
     namespace: string;
     /** PVC claim backing the shared session PVC the workspace roots live under. */
     sessionPvc?: string;

package/dist/sandbox/k8s-client.js

@@ -1,8 +1,9 @@
 /**
  * K8s-backed `createSandbox` / `teardown` / `isAlive`.
  *
- * Launches a sandbox Job with `CORTEX_BASE_URL` and `SANDBOX_CALLBACK_SECRET`
- * env vars; pod IP + port 8765 are the host/port Cortex POSTs `/exec` to.
+ * Launches a sandbox Job; pod IP + port 8765 are the host/port the host POSTs
+ * `/exec` to and polls. The pod initiates nothing: its confinement is a
+ * cluster-side NetworkPolicy, not an in-pod firewall.
  * Storage is wired via the shared session PVC: a flat read-only `volumeMount`
  * of the analysis tree at `/{resourceId}` plus a nested read-write mount of the
  * step's artifact dir, with the lib/ref stores mounted read-only at `/mnt/libs`
@@ -124,18 +125,11 @@ function buildJobSpec(session, sandboxSpec, hostLabels, config, identity, farm,
         toolchainSource: config.toolchainSource,
         cache: libsMounted && farm?.cachePath !== undefined,
     });
-    const transport = config.transport ?? "poll";
     const spec = sandboxSpec.resources;
     // Composed as one record, not as a list of `{name, value}`. A duplicate name
     // in the env of a container resolves at the kubelet, thus the later spread
     // must win here, not there.
     const env = Object.entries({
-        SANDBOX_TRANSPORT: transport,
-        // Poll mode never dials out, so the URL is omitted (matching the Docker
-        // backend) — the pod spec itself then documents that no callback egress
-        // is expected. sandbox-server neither reads nor requires it in poll mode.
-        ...(transport === "callback" ? { CORTEX_BASE_URL: config.cortexBaseUrl } : {}),
-        SANDBOX_CALLBACK_SECRET: identity.callbackSecret,
         ...threadLimitEnv(spec),
         ...plan.env,
         ...(sandboxSpec.extraEnv ?? {}),
@@ -400,8 +394,8 @@ function waitForJobGone(batchApi, namespace, name) {
  * owner workflow id must match this step's `ownerWorkflowId`.
  * Only a recovery re-run carries the same checkpointed identity, so a mismatch
  * means an (astronomically rare) name collision with a *different* step —
- * adopting its pod would HMAC-fail every callback, and deleting its Job would
- * kill a live sibling. Refuse loudly instead.
+ * adopting its pod would send the execs of this step to a sibling, and deleting
+ * its Job would kill a live sibling. Refuse loudly instead.
  */
 function createOrAdoptJob(batchApi, coreApi, namespace, sandboxId, ownerWorkflowId, job) {
     const createFailed = (status, cause) => ({
@@ -514,7 +508,6 @@ export function createK8sSandboxOps(config) {
                         host: ready.value.podIP,
                         port: SANDBOX_SERVER_PORT,
                         backend: "k8s",
-                        callbackSecret: identity.callbackSecret,
                     };
                     const registered = await trySandbox(() => config.registerSandbox(session, spec, ref), (status, cause) => ({
                         type: "container_create_failed",

package/dist/sandbox/liveness.d.ts

@@ -1,18 +1,13 @@
 /**
- * Transport-agnostic liveness escalation (the harness-sandbox-exec spec,
+ * Liveness escalation of the exec poll loop (the harness-sandbox-exec spec,
  * "sustained unavailability escalates to a liveness probe").
  *
- * The await loops observe the raw unreachability signal (consecutive
- * `unavailable` poll outcomes) but never adjudicate it themselves — poll
+ * The poll loop observes the raw unreachability signal (consecutive
+ * `unavailable` poll outcomes) but never adjudicates it itself — poll
  * failures conflate "unreachable" with "unknown execId / non-200". The
  * backend inspect (`SandboxClient.isAlive`) is the sole arbiter of dead
  * versus live-but-slow, invoked through {@link probeLiveness} once
  * {@link createEscalationPolicy} arms.
- *
- * Shared with the watchdog: {@link syntheticFailureReason} and
- * {@link syntheticFailureResult} are the one constructor for synthetic
- * failures, so reasons and result shape are identical no matter which
- * adjudicator (in-loop escalation or watchdog) produced them.
  */
 import type { ExecResult, SandboxLiveness, SandboxRef } from "./types.js";
 /**
@@ -35,9 +30,7 @@ export type ProbeVerdict = {
 };
 /**
  * The consecutive-unavailable counter: `unavailable` increments, `ok` resets,
- * and crossing `threshold` arms one probe and re-arms from zero. Pure state
- * over checkpointed poll outcomes, so a replaying loop walks the identical
- * poll/probe sequence.
+ * and crossing `threshold` arms one probe and re-arms from zero.
  */
 export declare function createEscalationPolicy(threshold?: number): {
     /** Record a poll outcome; true means "run the probe now". */
@@ -46,7 +39,7 @@ export declare function createEscalationPolicy(threshold?: number): {
 /**
  * Run the backend inspect and collapse it to a three-valued verdict. Never
  * throws: `isAlive` throws on transient backend API errors by contract, but
- * inside an await loop a failed probe is not a failed exec — the same
+ * inside the poll loop a failed probe is not a failed exec — the same
  * discipline as a failed poll — so a throw maps to `inconclusive` and the
  * caller resumes polling.
  */

package/dist/sandbox/liveness.js

@@ -1,18 +1,13 @@
 /**
- * Transport-agnostic liveness escalation (the harness-sandbox-exec spec,
+ * Liveness escalation of the exec poll loop (the harness-sandbox-exec spec,
  * "sustained unavailability escalates to a liveness probe").
  *
- * The await loops observe the raw unreachability signal (consecutive
- * `unavailable` poll outcomes) but never adjudicate it themselves — poll
+ * The poll loop observes the raw unreachability signal (consecutive
+ * `unavailable` poll outcomes) but never adjudicates it itself — poll
  * failures conflate "unreachable" with "unknown execId / non-200". The
  * backend inspect (`SandboxClient.isAlive`) is the sole arbiter of dead
  * versus live-but-slow, invoked through {@link probeLiveness} once
  * {@link createEscalationPolicy} arms.
- *
- * Shared with the watchdog: {@link syntheticFailureReason} and
- * {@link syntheticFailureResult} are the one constructor for synthetic
- * failures, so reasons and result shape are identical no matter which
- * adjudicator (in-loop escalation or watchdog) produced them.
  */
 /**
  * Consecutive `unavailable` polls tolerated before probing. On the fast poll
@@ -24,9 +19,7 @@
 export const PROBE_AFTER_UNAVAILABLE_POLLS = 4;
 /**
  * The consecutive-unavailable counter: `unavailable` increments, `ok` resets,
- * and crossing `threshold` arms one probe and re-arms from zero. Pure state
- * over checkpointed poll outcomes, so a replaying loop walks the identical
- * poll/probe sequence.
+ * and crossing `threshold` arms one probe and re-arms from zero.
  */
 export function createEscalationPolicy(threshold = PROBE_AFTER_UNAVAILABLE_POLLS) {
     let consecutiveUnavailable = 0;
@@ -47,7 +40,7 @@ export function createEscalationPolicy(threshold = PROBE_AFTER_UNAVAILABLE_POLLS
 /**
  * Run the backend inspect and collapse it to a three-valued verdict. Never
  * throws: `isAlive` throws on transient backend API errors by contract, but
- * inside an await loop a failed probe is not a failed exec — the same
+ * inside the poll loop a failed probe is not a failed exec — the same
  * discipline as a failed poll — so a throw maps to `inconclusive` and the
  * caller resumes polling.
  */

package/dist/sandbox/notification-sweep.d.ts

@@ -3,14 +3,11 @@
  * rows whose owning workflow has reached a terminal status (SUCCESS,
  * ERROR, CANCELLED).
  *
- * Background: a `DBOS.send` to an already-completed workflow accumulates
- * forever as `consumed=f`. The watchdog's
- * synthetic-failure send guarantees this happens at the protocol level —
- * a real `complete` may arrive microseconds before the watchdog and the
- * loser becomes a stuck notification.
+ * Background: a `DBOS.send` to a workflow that ends before it reads the
+ * message accumulates forever as `consumed=f` — for example the suspension
+ * notice of a child (`CHILD_SUSPENDED_TOPIC`) to a parent that already failed.
  *
- * Cadence is separate from the liveness watchdog (~5 minutes vs ~1
- * minute). Bounded delete batch keeps the lock window short.
+ * Cadence ~5 minutes. Bounded delete batch keeps the lock window short.
  *
  * Production reads the DBOS system DB via the app pool (DBOS by default
  * shares the database, only the pool is separate). The query function is

package/dist/sandbox/notification-sweep.js

@@ -3,14 +3,11 @@
  * rows whose owning workflow has reached a terminal status (SUCCESS,
  * ERROR, CANCELLED).
  *
- * Background: a `DBOS.send` to an already-completed workflow accumulates
- * forever as `consumed=f`. The watchdog's
- * synthetic-failure send guarantees this happens at the protocol level —
- * a real `complete` may arrive microseconds before the watchdog and the
- * loser becomes a stuck notification.
+ * Background: a `DBOS.send` to a workflow that ends before it reads the
+ * message accumulates forever as `consumed=f` — for example the suspension
+ * notice of a child (`CHILD_SUSPENDED_TOPIC`) to a parent that already failed.
  *
- * Cadence is separate from the liveness watchdog (~5 minutes vs ~1
- * minute). Bounded delete batch keeps the lock window short.
+ * Cadence ~5 minutes. Bounded delete batch keeps the lock window short.
  *
  * Production reads the DBOS system DB via the app pool (DBOS by default
  * shares the database, only the pool is separate). The query function is

package/dist/sandbox/reaper.d.ts

@@ -2,9 +2,9 @@
  * Sandbox reaper — the sole cleanup for orphaned sandboxes and stale registry
  * rows (see the harness-sandbox-exec spec, CONTEXT.md "Sandbox reaper").
  *
- * Distinct from the liveness watchdog (`sandbox/watchdog.ts`): the watchdog
- * sweeps registry→cluster and unblocks stuck recvs; the reaper sweeps
- * cluster→registry and garbage-collects. It lists every Cortex-managed sandbox
+ * The reaper sweeps cluster→registry and garbage-collects. A machine that dies
+ * under a running exec needs no sweep: the exec's own liveness probe ends it
+ * (`exec.ts`). The reaper lists every Cortex-managed sandbox
  * machine in the configured namespace, resolves each machine's recorded owner
  * workflow, and reaps the ones whose owner is terminal — tearing the machine
  * down and reconciling its step row. A machine whose owner does not resolve at

package/dist/sandbox/reaper.js

@@ -2,9 +2,9 @@
  * Sandbox reaper — the sole cleanup for orphaned sandboxes and stale registry
  * rows (see the harness-sandbox-exec spec, CONTEXT.md "Sandbox reaper").
  *
- * Distinct from the liveness watchdog (`sandbox/watchdog.ts`): the watchdog
- * sweeps registry→cluster and unblocks stuck recvs; the reaper sweeps
- * cluster→registry and garbage-collects. It lists every Cortex-managed sandbox
+ * The reaper sweeps cluster→registry and garbage-collects. A machine that dies
+ * under a running exec needs no sweep: the exec's own liveness probe ends it
+ * (`exec.ts`). The reaper lists every Cortex-managed sandbox
  * machine in the configured namespace, resolves each machine's recorded owner
  * workflow, and reaps the ones whose owner is terminal — tearing the machine
  * down and reconciling its step row. A machine whose owner does not resolve at

package/dist/sandbox/sandbox-error.d.ts

@@ -5,10 +5,9 @@
  * the K8s client ops (`k8s-client.ts`) — model failure as values: each external
  * op returns `ResultAsync<T, SandboxError>`. The ONLY `try/catch` against the
  * SDK/driver call lives in those files (via the `trySandbox` helper here);
- * everything up to the composition seam flows `ResultAsync`. (`submitExec`
- * (`submit-exec.ts`) is NOT on this channel — it wraps its own `/exec` POST in a
- * `DBOS.runStep` and throws on a non-202 so the step boundary records the
- * failure.)
+ * everything up to the composition seam flows `ResultAsync`. (The exec
+ * (`exec.ts`) is NOT on this channel — it runs as its own DBOS step and throws
+ * on a non-202 submit, so the step boundary records the failure.)
  *
  * House rules realized here (see `lib/result.ts`):
  *  - Absence / "already gone" is NOT an error. A 404 on inspect/isAlive is the
@@ -19,10 +18,10 @@
  *    owner-guard REFUSES, a submit the server rejects, a teardown the driver
  *    errors on, a liveness probe that errors.
  *  - Control-flow exceptions are NOT failures and are never captured as a
- *    `SandboxError`. The recv loop's `HardCancelError` / `ExecTimeoutError`
- *    (`await-exec.ts`) and DBOS's `DBOSWorkflowCancelledError` / `AbortError`
+ *    `SandboxError`. The exec's `ExecTimeoutError`
+ *    (`exec.ts`) and DBOS's `DBOSWorkflowCancelledError` / `AbortError`
  *    are control-flow signalling — they live OUTSIDE this error channel and
- *    propagate untouched. `await-exec.ts` is NOT converted; `trySandbox` only
+ *    propagate untouched. `exec.ts` is NOT converted; `trySandbox` only
  *    ever wraps the single SDK/HTTP call handed to it.
  *
  * `createSandbox` of the public `SandboxClient` gives each `SandboxError` as
@@ -34,8 +33,8 @@
  * composition seam: it builds the backend ops, maps each `err` of such an op to
  * a `SandboxFailure`, and `unwrapOrThrow`s it, so the seam throws the described
  * failure with the variant on `.cause` and on `.error`. A `catch` never sees
- * the raw variant. (`submitExec` is the exception — it is already its own DBOS
- * step and throws directly, so the seam forwards its `Promise<void>` as-is.)
+ * the raw variant. (`exec` is the exception — it is already its own DBOS
+ * step and throws directly, so the seam forwards its promise as-is.)
  */
 import { ResultAsync, type Result } from "neverthrow";
 import type { FarmLockError } from "./farm.js";
@@ -168,8 +167,8 @@ export declare function keepSuspendingRefusal(result: Result<SandboxRef, Sandbox
  *
  * `fn` runs the single SDK/HTTP call and returns the already-mapped value
  * (`T`). Keep `fn` to that one call plus trivial mapping; do NOT embed
- * control-flow that could throw a non-backend error (the recv loop's
- * `HardCancelError`/`ExecTimeoutError` and DBOS cancellation must stay outside
+ * control-flow that could throw a non-backend error (the exec's
+ * `ExecTimeoutError` and DBOS cancellation must stay outside
  * any `trySandbox` so they propagate as control-flow, never become an `err`).
  */
 export declare function trySandbox<T>(fn: () => Promise<T>, toError: (status: number | undefined, cause: unknown) => SandboxError): ResultAsync<T, SandboxError>;

package/dist/sandbox/sandbox-error.js

@@ -5,10 +5,9 @@
  * the K8s client ops (`k8s-client.ts`) — model failure as values: each external
  * op returns `ResultAsync<T, SandboxError>`. The ONLY `try/catch` against the
  * SDK/driver call lives in those files (via the `trySandbox` helper here);
- * everything up to the composition seam flows `ResultAsync`. (`submitExec`
- * (`submit-exec.ts`) is NOT on this channel — it wraps its own `/exec` POST in a
- * `DBOS.runStep` and throws on a non-202 so the step boundary records the
- * failure.)
+ * everything up to the composition seam flows `ResultAsync`. (The exec
+ * (`exec.ts`) is NOT on this channel — it runs as its own DBOS step and throws
+ * on a non-202 submit, so the step boundary records the failure.)
  *
  * House rules realized here (see `lib/result.ts`):
  *  - Absence / "already gone" is NOT an error. A 404 on inspect/isAlive is the
@@ -19,10 +18,10 @@
  *    owner-guard REFUSES, a submit the server rejects, a teardown the driver
  *    errors on, a liveness probe that errors.
  *  - Control-flow exceptions are NOT failures and are never captured as a
- *    `SandboxError`. The recv loop's `HardCancelError` / `ExecTimeoutError`
- *    (`await-exec.ts`) and DBOS's `DBOSWorkflowCancelledError` / `AbortError`
+ *    `SandboxError`. The exec's `ExecTimeoutError`
+ *    (`exec.ts`) and DBOS's `DBOSWorkflowCancelledError` / `AbortError`
  *    are control-flow signalling — they live OUTSIDE this error channel and
- *    propagate untouched. `await-exec.ts` is NOT converted; `trySandbox` only
+ *    propagate untouched. `exec.ts` is NOT converted; `trySandbox` only
  *    ever wraps the single SDK/HTTP call handed to it.
  *
  * `createSandbox` of the public `SandboxClient` gives each `SandboxError` as
@@ -34,8 +33,8 @@
  * composition seam: it builds the backend ops, maps each `err` of such an op to
  * a `SandboxFailure`, and `unwrapOrThrow`s it, so the seam throws the described
  * failure with the variant on `.cause` and on `.error`. A `catch` never sees
- * the raw variant. (`submitExec` is the exception — it is already its own DBOS
- * step and throws directly, so the seam forwards its `Promise<void>` as-is.)
+ * the raw variant. (`exec` is the exception — it is already its own DBOS
+ * step and throws directly, so the seam forwards its promise as-is.)
  */
 import { ResultAsync, err, ok } from "neverthrow";
 import { ZodError } from "zod";
@@ -167,8 +166,8 @@ export function keepSuspendingRefusal(result) {
  *
  * `fn` runs the single SDK/HTTP call and returns the already-mapped value
  * (`T`). Keep `fn` to that one call plus trivial mapping; do NOT embed
- * control-flow that could throw a non-backend error (the recv loop's
- * `HardCancelError`/`ExecTimeoutError` and DBOS cancellation must stay outside
+ * control-flow that could throw a non-backend error (the exec's
+ * `ExecTimeoutError` and DBOS cancellation must stay outside
  * any `trySandbox` so they propagate as control-flow, never become an `err`).
  */
 export function trySandbox(fn, toError) {

package/dist/sandbox/sandbox-step-translate.d.ts

@@ -49,7 +49,7 @@ export interface SandboxTreeDelta {
 }
 /** Extract the tree delta from a `data-sandbox-event` part, or null when the
  *  part is some other sandbox event. The wrapper shape is set by
- *  `run-exec.ts`: `{ type: "data-sandbox-event", data: { execId, event } }`
+ *  `run-exec.ts`: `{ type: "data-sandbox-event", data: { event } }`
  *  where `event` is the executor's `eventPayload`. */
 export declare function sandboxTreeDelta(part: {
     type: string;

package/dist/sandbox/sandbox-step-translate.js

@@ -45,7 +45,7 @@ export function activityForTool(name, input, resolveDetail) {
 }
 /** Extract the tree delta from a `data-sandbox-event` part, or null when the
  *  part is some other sandbox event. The wrapper shape is set by
- *  `run-exec.ts`: `{ type: "data-sandbox-event", data: { execId, event } }`
+ *  `run-exec.ts`: `{ type: "data-sandbox-event", data: { event } }`
  *  where `event` is the executor's `eventPayload`. */
 export function sandboxTreeDelta(part) {
     if (part.type !== "data-sandbox-event")

package/dist/sandbox/types.d.ts

@@ -1,12 +1,10 @@
 /**
  * Sandbox-client types — the wire/persistence shapes that cross the
- * submit/recv protocol (see the harness-sandbox-exec spec) and the active-sandbox registry.
+ * submit/poll protocol (see the harness-sandbox-exec spec) and the active-sandbox registry.
  *
- * `SandboxRef` is the in-memory handle the harness uses to talk to a live
- * sandbox; it carries the per-sandbox `callbackSecret` (see the harness-sandbox-exec spec). The
- * persistable subset is `PersistedSandboxRef` (from `harness/state/schema.ts`)
- * — that one OMITS the secret, which lives only in the cached
- * `createSandbox` DBOS step output.
+ * `SandboxRef` is the handle the harness uses to talk to a live sandbox. The
+ * active-sandbox registry persists the same shape (`PersistedSandboxRef`, from
+ * `harness/state/schema.ts`).
  */
 import type { ResultAsync } from "neverthrow";
 import { z } from "zod";
@@ -14,26 +12,12 @@ import type { RunSession } from "../auth/types.js";
 import type { ResourceSpec } from "../config/resource-limits.js";
 import type { GateFailure } from "../lib/hooks.js";
 import type { PackageQuery } from "./package-identity.js";
+import type { PersistedSandboxRef } from "../state/schema.js";
 export declare const SandboxBackend: z.ZodEnum<{
     docker: "docker";
     k8s: "k8s";
 }>;
 export type SandboxBackend = z.infer<typeof SandboxBackend>;
-/**
- * How a command's progress events and terminal result reach the host. Chosen by
- * the embedder at its composition root and carried into the container as
- * `SANDBOX_TRANSPORT`; backend-independent. The OSS default is `poll`.
- *
- * - `poll`: the host polls `GET /exec/{execId}?since={cursor}`; the sandbox
- *   never dials out and needs no egress.
- * - `callback`: the sandbox POSTs signed event/completion callbacks; the
- *   embedder runs an ingress. `GET /exec/{execId}` stays the recovery backstop.
- */
-export declare const SandboxTransportSchema: z.ZodEnum<{
-    poll: "poll";
-    callback: "callback";
-}>;
-export type SandboxTransport = z.infer<typeof SandboxTransportSchema>;
 /**
  * The declared owner of the sandbox toolchain. `"image"` states that the
  * image owns the interpreters, conda, and Node. `"store"` states that the
@@ -154,31 +138,14 @@ export type ExtendAnalysisFarm = (analysisId: string, queries: readonly PackageQ
  * Per-sandbox-machine liveness verdict. `oomKilled` is meaningful only when
  * `alive` is false: true when the backend reports the machine was killed for
  * exceeding its memory limit (Docker `State.OOMKilled`; K8s container
- * terminated reason `OOMKilled`) — the watchdog surfaces it as the
+ * terminated reason `OOMKilled`) — the exec surfaces it as the
  * `sandbox-oom-killed` failure reason instead of the generic `sandbox-dead`.
  */
 export interface SandboxLiveness {
     readonly alive: boolean;
     readonly oomKilled: boolean;
 }
-export declare const SandboxRefSchema: z.ZodObject<{
-    sandboxId: z.ZodString;
-    host: z.ZodString;
-    port: z.ZodNumber;
-    backend: z.ZodEnum<{
-        docker: "docker";
-        k8s: "k8s";
-    }>;
-    callbackSecret: z.ZodString;
-}, z.core.$strip>;
-export type SandboxRef = z.infer<typeof SandboxRefSchema>;
-/** Strip the secret before persisting to the active-sandbox registry. */
-export declare function toPersistedRef(ref: SandboxRef): {
-    sandboxId: string;
-    host: string;
-    port: number;
-    backend: SandboxBackend;
-};
+export type SandboxRef = PersistedSandboxRef;
 /**
  * One tracked file operation in the sandbox-server provenance frame.
  * Mirrors Go's `ProvenanceEntry` (`images/sandbox-base/server/provenance.go`):
@@ -190,8 +157,8 @@ export declare const ProvenanceFrameEntrySchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ProvenanceFrameEntry = z.infer<typeof ProvenanceFrameEntrySchema>;
 /**
- * Runtime file-I/O frame sandbox-server attaches to the `/complete`
- * callback. Mirrors Go's `provenancePayload` — every field is
+ * Runtime file-I/O frame sandbox-server attaches to the terminal result.
+ * Mirrors Go's `provenancePayload` — every field is
  * `omitempty` on the wire, so each arm defaults so a completion that
  * omits the frame (or any arm) still parses.
  */
@@ -228,9 +195,9 @@ export declare const ExecUsageSchema: z.ZodCatch<z.ZodOptional<z.ZodObject<{
 }, z.core.$strip>>>;
 export type ExecUsage = z.infer<typeof ExecUsageSchema>;
 /**
- * Final outcome of a single exec, returned by `awaitExec`. Mirrors the
- * sandbox-server completion payload plus a discriminant for synthetic
- * (watchdog-emitted) failures.
+ * Final outcome of a single exec, returned by `SandboxClient.exec`. Mirrors
+ * the sandbox-server completion payload plus a discriminant for a synthetic
+ * failure: the machine died under the exec.
  */
 export declare const ExecResultSchema: z.ZodObject<{
     execId: z.ZodString;
@@ -267,35 +234,10 @@ export declare const ExecResultSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type ExecResult = z.infer<typeof ExecResultSchema>;
-/**
- * Per-message envelope on the per-exec DBOS topic. Real callbacks carry
- * a non-null `signature` and `timestamp`; the in-process watchdog uses a
- * `null` signature + a `synthetic-failure` payload (see `await-exec.ts`).
- *
- * `payloadDigest` is the hex SHA-256 of the exact bytes sandbox-server POSTed.
- * The HMAC signs that digest rather than the body itself, so the digest is all
- * verification needs — and carrying it instead of the bytes keeps the message
- * from holding a second copy of a payload that can be arbitrarily large.
- * Re-serializing the parsed payload would not do: Go's `encoding/json`
- * HTML-escapes `<`, `>`, `&` by default, so a JS re-serialization diverges for
- * any output containing those characters (common in bioinformatics: FASTA
- * headers, shell stderr, command pipelines).
- *
- * `payloadRaw` is the superseded form, kept optional so messages already in
- * flight or persisted still verify.
- */
-export declare const ExecEventMessageSchema: z.ZodObject<{
-    payload: z.ZodUnknown;
-    payloadDigest: z.ZodOptional<z.ZodString>;
-    payloadRaw: z.ZodOptional<z.ZodString>;
-    signature: z.ZodNullable<z.ZodString>;
-    timestamp: z.ZodNullable<z.ZodNumber>;
-}, z.core.$strip>;
-export type ExecEventMessage = z.infer<typeof ExecEventMessageSchema>;
 /**
  * One buffered progress event in a poll response: the sandbox's monotonic
  * per-exec sequence number (the poll cursor) plus the event payload the host
- * forwards via `emit` — the same payload a callback-mode event POST carries.
+ * forwards via `emit`.
  */
 export declare const PollEventSchema: z.ZodObject<{
     seq: z.ZodNumber;
@@ -303,15 +245,18 @@ export declare const PollEventSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type PollEvent = z.infer<typeof PollEventSchema>;
 /**
- * Body of `GET /exec/{execId}?since={cursor}` in poll mode. Mirrors Go's
+ * Body of `GET /exec/{execId}?since={cursor}`. Mirrors Go's
  * `pollResponseBody`: the events newer than the caller's cursor, the new
  * high-water `cursor`, a `truncated` marker set once the ring shed an event,
  * and — once the exec is terminal — the completion `result` (with its
- * provenance frame). The whole body is HMAC-signed, verified exactly as a
- * pushed completion is.
+ * provenance frame).
  */
 export declare const PollResponseSchema: z.ZodObject<{
-    status: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        running: "running";
+        completed: "completed";
+    }>;
     events: z.ZodDefault<z.ZodArray<z.ZodObject<{
         seq: z.ZodNumber;
         payload: z.ZodUnknown;
@@ -355,23 +300,16 @@ export declare const PollResponseSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type PollResponse = z.infer<typeof PollResponseSchema>;
 /**
- * Done-marker shape the recv loop unwraps. Both real completion POSTs
- * (wrapped by the `/complete` handler) and watchdog synthetic-failure
- * sends use this discriminant.
+ * One command for `SandboxClient.exec`. It carries no exec id: the exec
+ * derives its id from the durable step it runs in.
  */
-export interface DoneMarker {
-    done: true;
-    result: ExecResult;
-}
-export interface SyntheticFailureMarker {
-    done: true;
-    result: ExecResult;
-    kind: "synthetic-failure";
-    reason: string;
+export interface ExecRequest {
+    readonly command: readonly string[];
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly timeoutSeconds?: number;
 }
-export declare function isDoneMarker(value: unknown): value is DoneMarker;
-export declare function isSyntheticFailure(value: unknown): value is SyntheticFailureMarker;
-/** Wire shape `submitExec` POSTs to sandbox-server's `/exec` (change 4). */
+/** Wire shape the exec POSTs to sandbox-server's `/exec`. */
 export interface SubmitExecBody {
     command: string[];
     execId: string;
@@ -389,9 +327,6 @@ export interface SubmitExecBody {
 }
 /** What a spawn needs beside its session. */
 export interface SandboxSpec {
-    /** The first `execId` that will fire against this sandbox; nullable for
-     *  early-create flows where the workflow mints the first execId later. */
-    execId?: string | null;
     /** Owning DBOS child workflow id (`"${parentRunId}-${N}"`). Recorded verbatim
      *  on the sandbox machine under `cortex/owner-workflow-id` so the reaper can
      *  map a cluster-side machine back to its workflow and check liveness. */
@@ -425,14 +360,12 @@ export type ResolveSandboxLabels = (session: RunSession) => ResultAsync<SandboxL
  * The identity minted for a sandbox machine *before* it is spawned — the
  * durable half of the two-step create (see the harness-sandbox-exec spec). Step 1 checkpoints this so a
  * recovery re-run of the spawn step adopts the already-created machine under
- * the same name and HMAC secret instead of leaking a second one.
+ * the same name instead of leaking a second one.
  */
 export interface SandboxIdentity {
     /** `sbx-{run8}-{uuid4}` — informative for `kubectl`, not load-bearing; the
      *  checkpoint, not the name, is what makes create idempotent. */
     sandboxId: string;
-    /** 32-byte base64 HMAC secret (see the harness-sandbox-exec spec); rides into the machine's env. */
-    callbackSecret: string;
 }
 /**
  * A sandbox machine the backend is running that Cortex *manages*
@@ -448,8 +381,7 @@ export interface ManagedSandbox {
     createdAtMs: number | null;
 }
 /**
- * Per-step `emit` callback handed to `awaitExec`. May be async — `awaitExec`
- * runs in the workflow body (see the harness-tools spec) and `await`s each emit so the body-path
- * `DBOS.writeStream` it drives lands at a deterministic function-ID (see the harness-durable-runtime spec).
+ * Progress callback of `SandboxClient.exec`, called with each sandbox event in
+ * sequence order. The exec awaits each call before it polls again.
  */
 export type ExecEmit = (event: unknown) => void | Promise<void>;