@coreplane/switchboard 0.0.0 → 1.18.0

package/dist/assets/src/execution/residentState.ts

@@ -0,0 +1,47 @@
+// The resident lifecycle vocabulary, shared by the resident Worker
+// (deploy/cloudflare-resident/worker.ts, which owns the transitions) and the
+// bot's executor selection (factory.ts, which decides what to do with a probed
+// state). One definition, no runtime imports, so a renamed or added state is a
+// compile error on BOTH sides instead of a silently changed gate.
+
+export type ResidentLifecycleState = "onboarding" | "warm" | "refreshing" | "restoring" | "degraded" | "down";
+
+/** States in which the resident serves the last snapshot and its /attach route
+ *  refuses nothing: the bot attaches. `degraded` is serviceable only for the
+ *  reason classes that leave the checkout intact — see `degradedIsServiceable`. */
+export const SERVICEABLE_STATES: ReadonlySet<ResidentLifecycleState> = new Set<ResidentLifecycleState>([
+  "warm",
+  "refreshing",
+  "degraded",
+]);
+
+// A `degraded` reason names its cause (docs/reference/specs/resident-repos.md item 7).
+// Only reasons that PROVE the previous checkout + dep cache are intact attach:
+// `github-unreachable: …` (the fetch failed before the checkout was touched)
+// and `alarm-missed: …` (the watchdog re-armed a dead chain; nothing ran).
+// `stale-mid-flight: …` does NOT qualify: it is stamped when a `refreshing`
+// marker was orphaned by a cycle that died mid-flight, and that death may have
+// been inside the rebuild lock section (after `git clean -fdx`, mid-install) —
+// exactly the torn checkout this gate exists to avoid; the +5s recovery cycle
+// rebuilds it within seconds anyway. A failure INSIDE the rebuild —
+// `checkout-update-failed`, `install-failed`, `build-failed`,
+// `snapshot-failed`, `refresh-failed` — leaves the checkout at a new sha with
+// absent/partial deps, and a fresh thread would hardlink that broken cache.
+// `disk-full: …` (`residentDisk.ts`) is not on the list on purpose: the
+// checkout may be intact, but a full disk cannot take a worktree, a credential
+// file, or even `/etc/gitconfig.lock`, so the attach would fail every time
+// (recorded as `github-unreachable`, every run would attach and die at
+// git-setup). Everything not on the allow-list, including unknown reasons,
+// stays cold.
+const SERVICEABLE_DEGRADED_REASON = /^(?:github-unreachable|alarm-missed)(?::|$)/;
+
+export function degradedIsServiceable(reason: string | undefined): boolean {
+  return SERVICEABLE_DEGRADED_REASON.test(reason ?? "");
+}
+
+/** The bot's attach decision for a probed `{state, reason}`: true only for
+ *  `warm`, `refreshing`, and a `degraded` whose reason proves the checkout intact. */
+export function isServiceable(state: string, reason?: string): boolean {
+  if (!SERVICEABLE_STATES.has(state as ResidentLifecycleState)) return false;
+  return state !== "degraded" || degradedIsServiceable(reason);
+}

package/dist/assets/src/execution/residentStepReport.ts

@@ -0,0 +1,98 @@
+import { redactSecrets, stripAnsi } from "../core/redact.js";
+
+// How a failed resident step describes itself (docs/reference/specs/resident-repos.md
+// item 53). Pure, so the shape is a unit test and not a live post-mortem.
+//
+// The rule this module exists to enforce: a failure report may never CHOOSE
+// between the two streams. It used to — `tail(r.stderr || r.stdout)` — and
+// that cost a whole diagnosis once: a resident went `down (provision-failed at
+// install: exit 1: [WARN] The "pnpm" field in package.json is no longer read
+// by pnpm …)`. That warning cannot fail an install: the same command prints
+// those exact bytes on stderr and exits 0 (reproducible on the same tree
+// inside the resident's own base image). The pnpm family reports through its
+// own logger on STDOUT, so `stderr || stdout` let a harmless warning shadow
+// the error that named the exit — and nothing else recorded the command's
+// output, so the real cause was gone for good.
+//
+// Every stream a step can write is therefore reported, labelled, tail-first
+// (a tool's error is its last output), each bounded on its own so one noisy
+// stream cannot crowd out the other.
+
+/** What the sandbox exec hands back for one command. */
+export interface StepResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  timedOut: boolean;
+}
+
+/** Chars kept per stream in the STORED reason — it travels into DO storage,
+ *  `GET /residents`, `repo list` and a Slack reply, so it stays short. The
+ *  full output goes to the Worker log instead (`stepFailureLog`). */
+export const STEP_REPORT_PER_STREAM = 400;
+
+/** Chars kept per stream in the LOG line: enough for a pnpm/vitest error
+ *  block with its context, still bounded so one runaway step cannot flood
+ *  the Worker's logs. */
+export const STEP_LOG_PER_STREAM = 4000;
+
+/** The last `budget` chars of `s`, marked with a leading `…` when cut. Empty
+ *  (after trimming) yields "" so the caller can drop the label entirely. */
+function tailOf(s: string, budget: number): string {
+  // Item 62: the tail lands in a stored reason and on a card — strip and
+  // redact BEFORE cutting, so a cut can never split a credential.
+  const trimmed = redactSecrets(stripAnsi(s)).trim();
+  if (trimmed.length <= budget) return trimmed;
+  return `…${trimmed.slice(-budget)}`;
+}
+
+function exitPhrase(r: StepResult): string {
+  return `exit ${r.exitCode}${r.timedOut ? " (timed out)" : ""}`;
+}
+
+/** The StepResult for a wait the SDK gave up on while the process was still
+ *  alive (`ProcessWaitTimeoutError`: "Process output did not complete within
+ *  <ms>ms") — after the caller killed it. It is the step's OWN timeout, shaped
+ *  exactly like one the supervisor enforced (`timedOut: true` → "(timed out)"
+ *  in the report), so `classifyRefreshFailure` files it as `<step>-failed`,
+ *  never as an interruption. `exitCode` is the status observed after the
+ *  kill, or -1 when the process still had not reported one: the report says
+ *  which, and never invents a status. */
+export function abandonedWaitStepResult(input: { detail: string; exitCode: number | null }): StepResult {
+  const exit = input.exitCode === null ? "killed, no exit status observed" : `killed, exit ${input.exitCode}`;
+  return {
+    stdout: "",
+    stderr: `${input.detail} — process was still running: ${exit}`,
+    exitCode: input.exitCode ?? -1,
+    timedOut: true,
+  };
+}
+
+/** The stored `provision-failed at <step>: <this>` / refresh-error detail.
+ *
+ *  Throws when handed a success: the only correct caller is a failure branch,
+ *  and a "failure" description of exit 0 would be a lie in the record. */
+export function describeStepFailure(r: StepResult, perStream = STEP_REPORT_PER_STREAM): string {
+  if (r.exitCode === 0 && !r.timedOut) {
+    throw new Error(`describeStepFailure: not a failure (exit ${r.exitCode})`);
+  }
+  const parts: string[] = [];
+  const out = tailOf(r.stdout, perStream);
+  const err = tailOf(r.stderr, perStream);
+  if (out) parts.push(`stdout: ${out}`);
+  if (err) parts.push(`stderr: ${err}`);
+  return `${exitPhrase(r)}: ${parts.length > 0 ? parts.join("; ") : "no output"}`;
+}
+
+/** The operator's escape hatch: what `console.log` writes when a step fails,
+ *  so the Worker log (observability is on for this Worker) holds the error
+ *  block itself even when the stored reason only had room for its tail. */
+export function stepFailureLog(step: string, r: StepResult, perStream = STEP_LOG_PER_STREAM): string {
+  const out = tailOf(r.stdout, perStream);
+  const err = tailOf(r.stderr, perStream);
+  return [
+    `step ${step} failed: ${exitPhrase(r)}`,
+    `--- stdout ---\n${out || "(empty)"}`,
+    `--- stderr ---\n${err || "(empty)"}`,
+  ].join("\n");
+}

package/dist/assets/src/execution/residentStepTrace.ts

@@ -0,0 +1,97 @@
+// The resident's own measurement of a request's steps (docs/reference/specs/tracing.md
+// item 19; docs/reference/specs/resident-repos.md item 63): every command the Worker runs
+// for one `/attach` or `/op` — clone, fetch, install, the mutex wait — as
+// offsets from the request's start, handed back in the answer's `trace` so
+// the bot grafts them under the span that made the call. A pure module both
+// sides import: the Worker records, the bot re-validates (residentTrace.ts).
+// No I/O, no clock of its own: the caller supplies every stamp.
+
+/** One measured step, in the resident's own time as offsets from its request start. */
+export type ResidentStep = {
+  /** The step's name — an identifier from the Worker's step vocabulary (`clone`,
+   *  `install`, `mutex_wait`…); sanitized on both sides. */
+  name: string;
+  /** Milliseconds after the request started. */
+  startMs: number;
+  durationMs: number;
+  status: "ok" | "error";
+  exitCode?: number;
+  timedOut?: boolean;
+  /** `mutex_wait` only: how long the request waited for the mirror lock. */
+  waitedMs?: number;
+};
+
+/** The most steps one answer carries, and the most bytes: an attach is about
+ *  a dozen steps, a full build a few dozen; past the cap the newest are kept. */
+export const STEP_TRACE_MAX = 64;
+export const STEP_TRACE_MAX_BYTES = 8 * 1024;
+export const STEP_NAME_MAX = 32;
+
+const STEP_NAME = /[^a-z0-9_-]+/g;
+
+/** A step name as the trace carries it: lowercase `[a-z0-9_-]`, at most 32
+ *  chars, `step` when nothing is left. */
+export function sanitizeStepName(raw: unknown): string {
+  const s = String(raw ?? "")
+    .toLowerCase()
+    .replace(STEP_NAME, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, STEP_NAME_MAX);
+  return s || "step";
+}
+
+export interface StepTrace {
+  /** Record one finished command. */
+  record(
+    step: string,
+    stamps: { startedAt: number; endedAt: number; exitCode?: number; timedOut?: boolean; ok?: boolean },
+  ): void;
+  /** Record a wait for the mirror lock that ended at `endedAt`. */
+  mutexWait(waitedMs: number, endedAt: number): void;
+  /** The steps so far, bounded, as offsets from `t0`. */
+  steps(): ResidentStep[];
+}
+
+/** A collector for one request: `t0` is the request's start on the Worker's clock. */
+export function createStepTrace(t0: number): StepTrace {
+  const steps: ResidentStep[] = [];
+  const sizes: number[] = [];
+  let bytes = 2; // the array's brackets
+  const push = (s: ResidentStep) => {
+    // Bounded by count and by bytes (a running total: each step's serialized
+    // size plus its comma); the newest steps are the ones a slow attach is
+    // about, so the oldest go first.
+    const size = JSON.stringify(s).length + 1;
+    steps.push(s);
+    sizes.push(size);
+    bytes += size;
+    while (steps.length > STEP_TRACE_MAX || bytes > STEP_TRACE_MAX_BYTES) {
+      steps.shift();
+      bytes -= sizes.shift() ?? 0;
+    }
+  };
+  return {
+    record(step, stamps) {
+      const ok = stamps.ok ?? ((stamps.exitCode === 0 || stamps.exitCode === undefined) && !stamps.timedOut);
+      push({
+        name: sanitizeStepName(step),
+        startMs: Math.max(0, Math.round(stamps.startedAt - t0)),
+        durationMs: Math.max(0, Math.round(stamps.endedAt - stamps.startedAt)),
+        status: ok ? "ok" : "error",
+        ...(stamps.exitCode !== undefined ? { exitCode: stamps.exitCode } : {}),
+        ...(stamps.timedOut ? { timedOut: true } : {}),
+      });
+    },
+    mutexWait(waitedMs, endedAt) {
+      const wait = Math.max(0, Math.round(waitedMs));
+      push({
+        name: "mutex_wait",
+        startMs: Math.max(0, Math.round(endedAt - wait - t0)),
+        durationMs: wait,
+        status: "ok",
+        waitedMs: wait,
+      });
+    },
+    steps: () => steps.map((s) => ({ ...s })),
+  };
+}

package/dist/assets/src/execution/residentSteps.ts

@@ -0,0 +1,99 @@
+// The resident's step vocabulary (docs/reference/specs/tracing.md item 15): every command
+// the resident Worker runs is named here, and only here. The Worker's runners
+// (`runOk`, `gitWithCred`, `buildUserRun`, `restoreExtracted` in
+// deploy/cloudflare-resident/worker.ts) take a `ResidentStepName`, so a step
+// the table does not know is a type error there; the run page's display table
+// reads the labels, so no grafted step ever renders as `a Switchboard step`.
+// Node-free: the Worker bundles this file.
+
+export const RESIDENT_STEP_LABELS = {
+  clone: "cloning the repo",
+  "checkout-clone": "cloning the checkout",
+  "worktree-clone": "cloning the worktree",
+  "worktree-detach": "checking out the expected commit",
+  "op-clone": "cloning the op tree",
+  fetch: "fetching the branch",
+  "wake-fetch": "fetching the latest commits",
+  "reclaim-fetch": "fetching to reclaim the mirror",
+  "for-each-ref": "listing the branches",
+  checkout: "checking out the branch",
+  "checkout-update": "updating the checkout",
+  "rev-parse": "reading the commit",
+  "cat-file": "checking the mirror for the commit",
+  "show-ref": "reading the branch tip",
+  "detect-default-branch": "detecting the default branch",
+  git: "a git command",
+  "git-setup": "configuring git",
+  "stage-perms": "securing the credential stage",
+  install: "installing dependencies",
+  build: "building",
+  test: "running the tests",
+  "clear-markers": "clearing the build markers",
+  "lockfile-key": "hashing the lockfile",
+  "deps-store-dir": "preparing the dependency store",
+  "deps-scratch": "cloning a scratch tree for the dependency install",
+  "deps-install": "installing the dependency store",
+  "deps-harden": "locking down the installed dependencies",
+  "deps-commit": "recording the installed dependencies",
+  "deps-adopt": "adopting the dependency store",
+  "deps-restore-scratch": "restoring dependencies to scratch",
+  "deps-restore-chown": "setting the restored dependencies' owner",
+  "deps-restore-commit": "recording the restored dependencies",
+  "deps-scratch-chown": "setting the dependency scratch owner",
+  "deps-evict": "evicting an old dependency store",
+  "unlink-deps-view": "unlinking the dependency view",
+  "clear-installing-marker": "clearing the install marker",
+  chown: "setting the workspace owner",
+  "worktree-chown": "setting the worktree owner",
+  "op-chown": "setting the op tree's owner",
+  "worktree-clean": "cleaning the worktree",
+  "clean-workspace": "cleaning the workspace",
+  "clean-before-restore": "cleaning before the restore",
+  "unmount-restores": "unmounting earlier restores",
+  "mirror-restore-extract": "extracting the mirror snapshot",
+  "checkout-restore-extract": "extracting the checkout snapshot",
+  "deps-restore-extract": "extracting the dependency snapshot",
+  evict: "evicting a stale tree",
+  "thread-dir": "preparing a directory",
+  "threads-dir": "preparing a directory",
+  "op-dir": "preparing a directory",
+  "ops-dir": "preparing a directory",
+  "stage-dir": "preparing a directory",
+  stat: "checking a file",
+  touch: "touching a marker",
+  nproc: "counting CPUs",
+  mutex_wait: "waiting for the workspace",
+  kill: "stopping the previous step",
+} as const satisfies Record<string, string>;
+
+/** A step named in the table. */
+export type ResidentStepLabelKey = keyof typeof RESIDENT_STEP_LABELS;
+
+/** A build-user step sweeps the previous step's leftover processes first; that sweep is named after the step it precedes. */
+export const STALE_SWEEP_SUFFIX = "-stale-sweep";
+
+/** Every name the Worker's command runners accept: a table entry, or a table entry's stale sweep. */
+export type ResidentStepName = ResidentStepLabelKey | `${ResidentStepLabelKey}${typeof STALE_SWEEP_SUFFIX}`;
+
+export const RESIDENT_STEP_NAMES: readonly ResidentStepLabelKey[] = Object.keys(
+  RESIDENT_STEP_LABELS,
+) as ResidentStepLabelKey[];
+
+function labelKeyOf(name: string): ResidentStepLabelKey | undefined {
+  return Object.prototype.hasOwnProperty.call(RESIDENT_STEP_LABELS, name) ? (name as ResidentStepLabelKey) : undefined;
+}
+
+/** The label for a step name, or undefined for a name outside the vocabulary. */
+export function residentStepLabel(name: string): string | undefined {
+  const direct = labelKeyOf(name);
+  if (direct !== undefined) return RESIDENT_STEP_LABELS[direct];
+  if (name.endsWith(STALE_SWEEP_SUFFIX)) {
+    const base = labelKeyOf(name.slice(0, -STALE_SWEEP_SUFFIX.length));
+    if (base !== undefined) return `clearing leftovers before ${RESIDENT_STEP_LABELS[base]}`;
+  }
+  return undefined;
+}
+
+export function isResidentStepName(name: string): name is ResidentStepName {
+  return residentStepLabel(name) !== undefined;
+}

package/dist/assets/src/execution/residentText.ts

@@ -0,0 +1,83 @@
+/** The one place resident-supplied text is made safe to show.
+ *
+ *  A resident's `reason`, `error` and `summary` strings are built from remote
+ *  output (git, npm, the container's shell) and from other threads' identifiers
+ *  (the disk-pressure refusal once listed them). They reach card titles, Slack
+ *  replies, `repo list` and stored records, so every one of them crosses this
+ *  module — on the resident at the write and the exit, and on the bot at the
+ *  parse, permanently: a reason stored by an older resident survives that
+ *  resident's deploy and its rollbacks.
+ *
+ *  Node-free and import-light so the resident Worker imports it by relative
+ *  path exactly like the bot does. */
+import { redactAndCap, stripAnsi } from "../core/redact.js";
+import type { ResidentLifecycleState } from "./residentState.js";
+
+/** Cap for one displayed resident string. Long enough for the longest reason
+ *  the resident legitimately builds — the disk-pressure refusal with its math,
+ *  eviction count and keep tokens (~230 chars), which item 55 shows whole — and
+ *  for the runtime-replaced guidance (~120); short enough for a card note. */
+export const RESIDENT_TEXT_CAP = 300;
+
+/** Strip terminal control sequences, redact credential shapes, cap. The identity
+ *  on the discriminator literals the bot compares (`runtime-replaced`,
+ *  `op-refused…`, `disk-pressure:`), pinned by test. */
+export function residentText(text: string): string {
+  return redactAndCap(stripAnsi(text), RESIDENT_TEXT_CAP);
+}
+
+const SANITIZED_FIELDS = ["error", "reason", "summary"] as const;
+
+/** How deep the sanitizer descends. The deepest resident shape today is
+ *  `/residents` → `residents[]` → `live` → `reason` (depth 3); the bound exists
+ *  so a hostile body cannot make the walk unbounded. */
+const SANITIZE_DEPTH = 4;
+
+/** A parsed resident body with its free-text fields made safe, at every level:
+ *  `/residents` nests each resident's `state`/`reason` (or an `error`) under
+ *  `residents[].live`, and `repo list` renders those. In each plain object only
+ *  `error`, `reason` and `summary` are touched (when strings); `stderr` is
+ *  rewritten only when it mirrors `error` (the thread routes' failure shape
+ *  copies the error into stderr). Every other field — `needs`, `state`,
+ *  `stdout`, `status`, bindings, numbers — passes through untouched. Arrays are
+ *  walked; scalars pass through; the input is never mutated. */
+export function sanitizeResidentBody<T>(data: T): T {
+  return walk(data, SANITIZE_DEPTH) as T;
+}
+
+function walk(value: unknown, depth: number): unknown {
+  if (value === null || typeof value !== "object" || depth < 0) return value;
+  if (Array.isArray(value)) return value.map((v) => walk(v, depth - 1));
+  const src = value as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const [key, v] of Object.entries(src)) {
+    out[key] =
+      (SANITIZED_FIELDS as readonly string[]).includes(key) && typeof v === "string"
+        ? residentText(v)
+        : walk(v, depth - 1);
+  }
+  if (typeof src.stderr === "string" && src.stderr === src.error && typeof out.error === "string") {
+    out.stderr = out.error;
+  }
+  return out;
+}
+
+/** The states a probe may report: the resident's own lifecycle union plus the
+ *  two the bot mints locally. Anything else — a future state, or free text from
+ *  a hostile body — reads as `unknown`, which `isServiceable` refuses. */
+export type ProbeState = ResidentLifecycleState | "not-onboarded" | "unknown";
+
+const PROBE_STATES: ReadonlySet<string> = new Set<ProbeState>([
+  "onboarding",
+  "warm",
+  "refreshing",
+  "restoring",
+  "degraded",
+  "down",
+  "not-onboarded",
+  "unknown",
+]);
+
+export function residentState(value: unknown): ProbeState {
+  return typeof value === "string" && PROBE_STATES.has(value) ? (value as ProbeState) : "unknown";
+}

package/dist/assets/src/execution/residentTrace.ts

@@ -0,0 +1,119 @@
+// The bot's side of the resident's step trace (docs/reference/specs/tracing.md item 19):
+// an Anti-Corruption Layer at the parse boundary. Whatever the resident sent
+// is rebuilt field by field from an allowlist — names sanitized, numbers
+// finite and clamped, status a literal, error text dropped — and then grafted
+// under the span that made the call, rebased to that span's start and clipped
+// to now, so a skewed, oversized, orphaned, mis-named or hostile trace can
+// only ever produce fewer, shorter, plainly-named spans.
+
+import type { Span } from "../core/trace/types.js";
+import type { SpanAttrs } from "../core/trace/attrs.js";
+import { sanitizeStepName, STEP_TRACE_MAX, STEP_TRACE_MAX_BYTES, type ResidentStep } from "./residentStepTrace.js";
+
+/** Every step the resident's answer carries, made safe. Anything that is not a
+ *  well-formed step is dropped; the list is bounded like the Worker's. */
+export function sanitizeGraftedSteps(raw: unknown): ResidentStep[] {
+  if (!Array.isArray(raw)) return [];
+  const out: ResidentStep[] = [];
+  for (const item of raw) {
+    if (typeof item !== "object" || item === null) continue;
+    const r = item as Record<string, unknown>;
+    if (!finite(r.startMs) || !finite(r.durationMs)) continue;
+    const step: ResidentStep = {
+      name: sanitizeStepName(r.name),
+      startMs: Math.max(0, Math.round(r.startMs)),
+      durationMs: Math.max(0, Math.round(r.durationMs)),
+      status: r.status === "error" ? "error" : "ok",
+    };
+    if (finite(r.exitCode) && Number.isInteger(r.exitCode) && r.exitCode >= 0 && r.exitCode <= 255) {
+      step.exitCode = r.exitCode;
+    }
+    if (r.timedOut === true) step.timedOut = true;
+    if (finite(r.waitedMs)) step.waitedMs = Math.max(0, Math.round(r.waitedMs));
+    out.push(step);
+    if (out.length > STEP_TRACE_MAX) out.shift();
+  }
+  while (out.length > 0 && JSON.stringify(out).length > STEP_TRACE_MAX_BYTES) out.shift();
+  return out;
+}
+
+function finite(v: unknown): v is number {
+  return typeof v === "number" && Number.isFinite(v);
+}
+
+/** The steps a failed request ran, pinned on the error it became. */
+export interface ResidentTrace {
+  steps: ResidentStep[];
+  residentMs?: number;
+}
+
+const TRACE_OF = new WeakMap<object, ResidentTrace>();
+
+/** Pin a failed request's sanitized steps on the error that reports it, so a
+ *  caller that catches the error (or wraps it as a `cause`) can still graft
+ *  them: a failed attach's trace is the one that says which step blew the
+ *  budget. Returns the same error. */
+export function withResidentTrace<E extends object>(err: E, trace: ResidentTrace): E {
+  TRACE_OF.set(err, trace);
+  return err;
+}
+
+/** The trace pinned on `err` or on one of its causes (to depth 5), if any. */
+export function residentTraceOf(err: unknown): ResidentTrace | undefined {
+  let cur: unknown = err;
+  for (let depth = 0; depth < 5 && typeof cur === "object" && cur !== null; depth++) {
+    const found = TRACE_OF.get(cur);
+    if (found) return found;
+    cur = (cur as { cause?: unknown }).cause;
+  }
+  return undefined;
+}
+
+export interface GraftInput {
+  /** The span that made the call (`dispatch.workspace.attach`, `run.command`). */
+  parent: Span;
+  /** The graft prefix: the parent's own name, so the steps read `<parent>.<step>`. */
+  prefix: "dispatch.workspace.attach" | "run.command" | "resident";
+  /** The bot's stamp for the request's start — the parent span's start. */
+  baseAt: number;
+  /** The bot's now: no grafted span ends after it. */
+  clipAt: number;
+  /** The resident's own total for the request (`attachMs`, `durationMs`), for
+   *  `clockSkewMs`: the bot's wait minus this, signed (negative = the clocks
+   *  disagree). */
+  residentTotalMs?: number;
+}
+
+/** Graft sanitized steps under the parent: each becomes `<prefix>.<name>`,
+ *  rebased so the resident's request start is the parent's start and clipped
+ *  to `clipAt`. Returns how many landed. `clockSkewMs` — the difference between
+ *  what the bot saw and what the resident measured (network and overhead) —
+ *  goes on the parent. */
+export function graftResidentSteps(steps: readonly ResidentStep[], input: GraftInput): number {
+  const { parent, prefix, baseAt, clipAt } = input;
+  let grafted = 0;
+  for (const step of steps) {
+    const startedAt = Math.min(clipAt, baseAt + step.startMs);
+    const endedAt = Math.min(clipAt, startedAt + step.durationMs);
+    const attrs: SpanAttrs = {
+      backend: "resident",
+      ...(step.exitCode !== undefined ? { exitCode: step.exitCode } : {}),
+      ...(step.timedOut ? { timedOut: true } : {}),
+      ...(step.waitedMs !== undefined ? { waitedMs: step.waitedMs } : {}),
+    };
+    parent.graft(`${prefix}.${step.name}`, {
+      startedAt,
+      endedAt,
+      status: step.status,
+      attrs,
+      ...(step.status === "error" ? { errorKind: "infra" as const } : {}),
+    });
+    grafted++;
+  }
+  if (input.residentTotalMs !== undefined) {
+    // Signed on purpose: negative when the resident measured more than the bot
+    // waited, i.e. the two clocks disagree — as worth seeing as the overhead.
+    parent.setAttrs({ clockSkewMs: Math.max(0, clipAt - baseAt) - Math.max(0, input.residentTotalMs) });
+  }
+  return grafted;
+}

package/dist/assets/src/execution/sandboxEnv.ts

@@ -0,0 +1,42 @@
+// The env map a per-thread sandbox request carries (docs/reference/specs/execution.md
+// item 5): ONE reader, shared by the sandbox Worker and its tests. Deliberately
+// free of node: imports so wrangler can bundle it into the Worker, like
+// bashTimeout.ts, shellQuote.ts and sandboxErrors.ts.
+//
+// Why the body and not headers: Workers Logs record every invocation's request
+// HEADERS and redact them by a name heuristic — a header named like a token
+// (`x-env-gh_token`) shows as REDACTED, but any other env name
+// (`x-env-PROBE_VAR: hello`) is logged in clear. Request bodies are not
+// recorded. So the executor sends the map as `env` in the JSON body on every
+// route and the Worker reads it from there — the ONLY channel. Request headers
+// are never a credential channel.
+
+/** A shell identifier: what an env NAME must be after upper-casing. Same rule
+ *  as the resident Worker's `ENV_NAME_RE`; anything else is dropped, never
+ *  interpolated. */
+export const ENV_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
+
+/** The validated env map for one request, read from `body.env` alone (an
+ *  object of string values). Names are upper-cased and must match
+ *  `ENV_NAME_PATTERN`; non-string values and an `env` that is not a plain
+ *  object are dropped. Request headers are never read — Workers Logs record
+ *  them (see above). Never throws — a malformed request yields `{}`. */
+export function envFromRequest(req: { body: unknown }): Record<string, string> {
+  const out: Record<string, string> = {};
+  const env = isPlainObject(req.body) ? req.body.env : undefined;
+  if (isPlainObject(env)) {
+    for (const [name, value] of Object.entries(env)) put(out, name, value);
+  }
+  return out;
+}
+
+function put(out: Record<string, string>, rawName: string, value: unknown): void {
+  if (typeof value !== "string") return;
+  const name = rawName.toUpperCase();
+  if (!ENV_NAME_PATTERN.test(name)) return;
+  out[name] = value;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}