@agent-compose/sdk 0.8.2 → 0.8.3

package/src/agent/desktop-open.ts

@@ -0,0 +1,418 @@
+/**
+ * `ac-open` — the in-guest desktop launcher that SURVIVES the command that
+ * invoked it.
+ *
+ * Why it exists (the 2026-08-16 cloud-desktop transcript): the sandbox exec
+ * layer (E2B envd) runs each command as its own session/process group and
+ * reaps that whole group when the command returns — and a child that inherits
+ * the exec's stdout/stderr pipes tethers the exec's stream to its own
+ * lifetime. So a GUI app launched with a plain `&` dies the moment the
+ * launching shell finishes ("It exited when the shell finished" — the agent's
+ * own words, after 8 turns of desktop archaeology). This is the SAME failure
+ * class as the v0.10.39/40 runner regression, fixed there with
+ * `setsid + >/dev/null 2>&1 </dev/null + pidfile` (sdk/src/runtimes/
+ * _cli-agent.ts — see its LOAD-BEARING comment). `ac-open` packages that
+ * exact discipline as a one-word verb so no agent ever has to rediscover it.
+ *
+ * ONE script, TWO delivery doors (the ac-record pattern,
+ * server/src/sandbox/attach/desktop-recorder.ts):
+ *   - BAKED into the desktop-carrying E2B images by the template recipe
+ *     (infra/e2b-template/parts.ts DESKTOP_OPEN_INSTALL) — covers workflow
+ *     runs and fresh session images;
+ *   - INSTALLED at session desktop-ensure by the server
+ *     (server/src/sandbox/persistent.ts ensureSessionDesktop) — covers
+ *     GRANDFATHERED session images that predate the bake, on every fresh boot.
+ * Both doors run `installDesktopOpenCmd()`, a plain truncating rewrite, so a
+ * contract change reaches old VMs on the next boot.
+ *
+ * The install also shims `xdg-open` and `sensible-browser` at /usr/local/bin
+ * (which precedes /usr/bin on PATH — the VS Code wrapper precedent), so
+ * generic "open a URL" flows inherit the detach semantics instead of dying
+ * with the exec.
+ *
+ * This module composes STRINGS only (pure + unit-tested, the
+ * desktop-recorder.ts posture); nothing here touches a sandbox.
+ */
+
+/** Where the launcher lands on the guest PATH. */
+export const AC_OPEN_PATH = "/usr/local/bin/ac-open";
+
+/** SHARED in-guest state dir: the browser-backfill markers, written by ROOT
+ *  (the backfill runs sudo) and only ever READ by ac-open. /tmp (ext4) —
+ *  machine-tier state that dies with the VM, exactly like the recorder's.
+ *
+ *  ac-open's own pidfiles + logs do NOT live here — they live in a PER-UID
+ *  sibling (`${AC_OPEN_STATE_DIR}.<uid>`, composed in the script). The
+ *  2026-08-21 owner transcript is why: the backfill's root-owned `mkdir -p`
+ *  landed this dir 0755 root:root, the session user's `>>"$LOG"` redirect
+ *  then failed, and the spawned subshell died before chromium ever ran —
+ *  surfacing as "chromium exited immediately: see …/browser.log" with an
+ *  EMPTY log (the redirect that would have written it is what failed). A
+ *  per-uid dir makes the launcher's writes collision-free for every
+ *  identity (root workflow runner AND the default session user). */
+export const AC_OPEN_STATE_DIR = "/tmp/.ac-desktop-open";
+
+/** Generic-open entrypoints routed through the launcher. */
+export const AC_OPEN_SHIM_PATHS = [
+  "/usr/local/bin/xdg-open",
+  "/usr/local/bin/sensible-browser",
+] as const;
+
+/**
+ * Browser-backfill marker protocol (self-healing browser presence). The
+ * server's boot-time desktop-ensure detects a desktop-carrying image WITHOUT
+ * chromium — only possible on GRANDFATHERED bakes, where the chromium install
+ * was tolerant (`|| true`) before the 2026-08-16 hard-install — and
+ * apt-installs it in the BACKGROUND, with the same setsid + stdio-redirect +
+ * pidfile detach discipline ac-open itself uses, so no boot path ever blocks
+ * on apt (20-40s). These markers are the shared contract: `browserBackfillCmd`
+ * writes them, `browserBackfillStatusCmd` and the ac-open script read them —
+ * that's how ac-open answers the THIRD state honestly (browser missing but
+ * ARRIVING — retry) instead of "no browser, give up".
+ */
+export const BROWSER_BACKFILL_PIDFILE = `${AC_OPEN_STATE_DIR}/browser-install.pid`;
+export const BROWSER_BACKFILL_LOG = `${AC_OPEN_STATE_DIR}/browser-install.log`;
+export const BROWSER_BACKFILL_FAILED = `${AC_OPEN_STATE_DIR}/browser-install.failed`;
+
+/** The PINNED third-state line ac-open prints while the background install
+ *  runs: honest, actionable, and never an invitation to give up or to mount
+ *  an apt expedition of the agent's own. */
+export const BROWSER_INSTALL_IN_PROGRESS_MSG =
+  "ac-open: no browser YET — the platform is installing chromium in the background right now; retry this exact command in ~30s";
+
+/**
+ * The `ac-open` script body. POSIX sh (dash is /bin/sh on the Debian base).
+ *
+ * Contract, pinned by the unit tests:
+ *   - every spawn is `setsid <cmd> </dev/null >>"$LOG" 2>&1 &` — its own
+ *     session (survives the exec's process-group reap), stdio OFF the exec's
+ *     pipes (so the exec's stream can settle), a durable pidfile;
+ *   - pidfiles + logs live in a PER-UID state dir (`$D`), so the root runner
+ *     and the session user never fight over one root-owned dir (the
+ *     2026-08-21 "exited immediately, empty log" failure — see
+ *     AC_OPEN_STATE_DIR's header); the shared dir (`$M`) is read-only here,
+ *     for the backfill markers root writes;
+ *   - IDEMPOTENT: re-invoking for a running app FOCUSES its window
+ *     (xdotool windowactivate) instead of spawning a second copy; the
+ *     browser and file manager are singletons, so a re-invoke hands the
+ *     target to the existing instance (a new tab / window) by design.
+ *     Liveness checks are SAME-UID only (`pgrep -u`): another identity's
+ *     instance shares neither profile nor single-instance socket, so it can
+ *     neither take a hand-off nor make this spawn redundant. And a fresh
+ *     spawn that exits within the liveness window while a same-uid instance
+ *     is alive IS the hand-off (single-instance apps hand the target over
+ *     and exit 0) — reported as success, never as a crash. N calls =
+ *     N tabs, zero crashes;
+ *   - HONEST degrades, one line each: no display → say so; no browser /
+ *     unknown app → name the missing tool and tell the agent to REPORT it
+ *     rather than mount a package-manager expedition. A REAL immediate
+ *     death carries the app's own log tail as the cause.
+ */
+export const AC_OPEN_SCRIPT = `#!/bin/sh
+# ac-open — open a URL, file, or GUI app on this machine's desktop, DETACHED.
+#
+#   ac-open https://github.com     the browser (a running instance gets a tab)
+#   ac-open ./report.html          a local file, in the browser
+#   ac-open .                      a directory, in the file manager
+#   ac-open gimp [args...]         any GUI app by command name
+#
+# Why: the sandbox reaps each exec'd command's process group when the command
+# returns, so a GUI app launched with a plain \`&\` dies the moment the
+# launching shell finishes. ac-open detaches the app into its own session
+# (setsid, stdio off the exec's pipes), records a pidfile, and returns at
+# once; re-invoking it for a running app focuses the existing window instead
+# of spawning a second copy. Logs + pidfiles: /tmp/.ac-desktop-open.<uid>/.
+# Written by agent-compose (sdk/src/agent/desktop-open.ts) — do not edit in place.
+set -u
+export DISPLAY="\${DISPLAY:-:0}"
+# Per-UID state (pidfiles + logs): the shared dir is root-owned when the
+# backfill created it, and a user-side >>$LOG into a root 0755 dir fails
+# BEFORE the app runs — the false "exited immediately" with an empty log.
+D="/tmp/.ac-desktop-open.$(id -u)"
+# Shared, root-written backfill markers — READ-ONLY here.
+M=/tmp/.ac-desktop-open
+mkdir -p "$D" 2>/dev/null || true
+[ -w "$D" ] || { echo "ac-open: state dir $D is not writable by uid $(id -u)" >&2; exit 1; }
+
+[ $# -ge 1 ] || { echo 'usage: ac-open <url|file|dir|app> [args...]' >&2; exit 2; }
+TARGET=$1; shift
+
+# No display = no desktop on this image. One honest line, no expedition.
+if ! timeout 3 xdotool getdisplaygeometry >/dev/null 2>&1; then
+  echo "ac-open: no desktop display on $DISPLAY — this machine has no GUI session up" >&2
+  exit 1
+fi
+
+pick_browser() {
+  for b in chromium chromium-browser x-www-browser google-chrome; do
+    command -v "$b" >/dev/null 2>&1 && { echo "$b"; return 0; }
+  done
+  return 1
+}
+
+# Best-effort: raise the newest visible window whose class matches $1.
+focus_class() {
+  WID=$(xdotool search --onlyvisible --class "$1" 2>/dev/null | tail -1) || WID=''
+  [ -n "\${WID:-}" ] && xdotool windowactivate "$WID" 2>/dev/null || true
+}
+
+# Same-UID instance probe: another identity's instance shares neither profile
+# nor single-instance socket, so only our own uid's counts as "running".
+alive_same_uid() { pgrep -x -u "$(id -u)" "$1" >/dev/null 2>&1; }
+
+# Singleton apps (browser, file manager): the second invocation hands the
+# target to the running instance and exits — that IS the idempotent path, so
+# spawn detached every time and only liveness-check a FRESH instance.
+singleton_open() { # $1 = state key, rest = command + target
+  NAME=$1; shift
+  BIN=$(basename "$1")
+  PIDFILE=$D/$NAME.pid; LOG=$D/$NAME.log
+  RUNNING=0
+  alive_same_uid "$BIN" && RUNNING=1
+  [ "$RUNNING" = 0 ] && [ -f "$PIDFILE" ] && kill -0 "$(cat "$PIDFILE" 2>/dev/null)" 2>/dev/null && RUNNING=1
+  setsid "$@" </dev/null >>"$LOG" 2>&1 &
+  PID=$!
+  if [ "$RUNNING" = 1 ]; then
+    sleep 1
+    focus_class "$BIN"
+    echo "ac-open: handed off to the running $BIN — no second window"
+    return 0
+  fi
+  echo "$PID" > "$PIDFILE"
+  sleep 1
+  if ! kill -0 "$PID" 2>/dev/null; then
+    # Died within the liveness window — but if OUR instance of $BIN is alive
+    # NOW, this was the single-instance HAND-OFF: the pre-check raced a
+    # still-starting instance, the fresh process handed the target over and
+    # exited 0. That is success (N calls = N tabs), never a crash report.
+    if alive_same_uid "$BIN"; then
+      focus_class "$BIN"
+      echo "ac-open: handed off to the running $BIN — no second window"
+      return 0
+    fi
+    TAIL=$(tail -c 300 "$LOG" 2>/dev/null | tr '\\n' ' ')
+    echo "ac-open: $BIN exited immediately: \${TAIL:-no output captured — see $LOG}" >&2
+    exit 1
+  fi
+  focus_class "$BIN"
+  echo "ac-open: launched $BIN (pid $PID), detached — it survives this command"
+}
+
+open_url() { # $1 = url
+  B=$(pick_browser) || {
+    # Grandfathered image mid-heal: the boot-time desktop-ensure found no
+    # browser and detached an apt install (browserBackfillCmd — the pidfile
+    # below is ITS single-flight marker, root-written in the SHARED dir).
+    # Third honest state: arriving.
+    if [ -f "$M/browser-install.pid" ] && kill -0 "$(cat "$M/browser-install.pid" 2>/dev/null)" 2>/dev/null; then
+      echo "${BROWSER_INSTALL_IN_PROGRESS_MSG}" >&2
+      exit 75
+    fi
+    if [ -f "$M/browser-install.failed" ]; then
+      TAIL=$(tail -c 300 "$M/browser-install.log" 2>/dev/null | tr '\\n' ' ')
+      echo "ac-open: the platform's background chromium install FAILED: \${TAIL:-see $M/browser-install.log} — report that cause in one line; do not apt-get one yourself." >&2
+      exit 1
+    fi
+    echo "ac-open: no graphical browser on this image (expected chromium) — cannot open $1. Report the missing browser in one line; do not apt-get one mid-session." >&2
+    exit 1
+  }
+  singleton_open browser "$B" "$1"
+}
+
+open_app() { # $1 = command, rest = args
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "ac-open: '$1' is not installed on this machine — report the missing tool in one line instead of package-hunting for it" >&2
+    exit 127
+  }
+  BIN=$(basename "$1"); PIDFILE=$D/app-$BIN.pid; LOG=$D/app-$BIN.log
+  OLD=$(cat "$PIDFILE" 2>/dev/null || true)
+  if [ -n "\${OLD:-}" ] && kill -0 "$OLD" 2>/dev/null; then
+    WID=$(xdotool search --onlyvisible --pid "$OLD" 2>/dev/null | tail -1) || WID=''
+    [ -z "\${WID:-}" ] && { WID=$(xdotool search --onlyvisible --class "$BIN" 2>/dev/null | tail -1) || WID=''; }
+    [ -n "\${WID:-}" ] && xdotool windowactivate "$WID" 2>/dev/null || true
+    echo "ac-open: $BIN is already running (pid $OLD) — focused it instead of starting a second copy"
+    exit 0
+  fi
+  CMD=$1; shift
+  setsid "$CMD" "$@" </dev/null >>"$LOG" 2>&1 &
+  PID=$!
+  echo "$PID" > "$PIDFILE"
+  sleep 1
+  if ! kill -0 "$PID" 2>/dev/null; then
+    # Same hand-off grace as the singletons: VS Code and friends are
+    # single-instance too — a fresh spawn that exits at once while our own
+    # instance is alive HANDED OFF, it did not crash.
+    if alive_same_uid "$BIN"; then
+      focus_class "$BIN"
+      echo "ac-open: handed off to the running $BIN — no second window"
+      exit 0
+    fi
+    TAIL=$(tail -c 300 "$LOG" 2>/dev/null | tr '\\n' ' ')
+    echo "ac-open: $BIN exited immediately: \${TAIL:-no output captured — see $LOG}" >&2
+    exit 1
+  fi
+  echo "ac-open: launched $BIN (pid $PID), detached — it survives this command"
+}
+
+case "$TARGET" in
+  http://*|https://*|file://*|about:*|chrome://*)
+    open_url "$TARGET" ;;
+  localhost|localhost:*|localhost/*|127.0.0.1|127.0.0.1:*|127.0.0.1/*)
+    open_url "http://$TARGET" ;;
+  *)
+    if [ -d "$TARGET" ]; then
+      command -v pcmanfm >/dev/null 2>&1 || {
+        echo "ac-open: no file manager on this image (expected pcmanfm) — report it in one line" >&2
+        exit 1
+      }
+      case "$TARGET" in /*) ABS=$TARGET ;; *) ABS=$PWD/$TARGET ;; esac
+      singleton_open files pcmanfm "$ABS"
+    elif [ -f "$TARGET" ]; then
+      case "$TARGET" in /*) ABS=$TARGET ;; *) ABS=$PWD/$TARGET ;; esac
+      open_url "file://$ABS"
+    else
+      open_app "$TARGET" "$@"
+    fi ;;
+esac
+`;
+
+/** Shim body for the generic-open entrypoints (`xdg-open`,
+ *  `sensible-browser`): exec straight into the detaching launcher, so any
+ *  tool that "opens a URL" survives its exec too. */
+export const AC_OPEN_SHIM = `#!/bin/sh
+# agent-compose: generic open routes through ac-open (the detaching launcher).
+exec ${AC_OPEN_PATH} "$@"
+`;
+
+/**
+ * Install (or refresh) `ac-open` + the generic-open shims — run as root.
+ * The script carries `$`/quotes/backslashes, so it rides the base64 idiom
+ * (the WRITE_AGENTS_MD / installRecorderCmd pattern): escaping-proof through
+ * the sandbox command channel. Always a plain truncating rewrite — the files
+ * are wholly platform-owned and tiny, so idempotence is free and a contract
+ * change reaches grandfathered VMs on the next session boot. Each write is
+ * `sh -n`-checked so a corrupted transit fails the install loudly, never the
+ * agent's first `ac-open`.
+ */
+export function installDesktopOpenCmd(): string {
+  const scriptB64 = Buffer.from(AC_OPEN_SCRIPT, "utf8").toString("base64");
+  const shimB64 = Buffer.from(AC_OPEN_SHIM, "utf8").toString("base64");
+  return [
+    `printf %s '${scriptB64}' | base64 -d > ${AC_OPEN_PATH}`,
+    `chmod 0755 ${AC_OPEN_PATH}`,
+    `sh -n ${AC_OPEN_PATH}`,
+    ...AC_OPEN_SHIM_PATHS.flatMap((p) => [
+      `printf %s '${shimB64}' | base64 -d > ${p}`,
+      `chmod 0755 ${p}`,
+      `sh -n ${p}`,
+    ]),
+  ].join(" && ");
+}
+
+/**
+ * Chromium session-desktop defaults — SINGLE-SOURCED here (the ac-open
+ * two-door pattern): baked into fresh images by infra/e2b-template/parts.ts
+ * (CHROMIUM_DEFAULTS_INSTALL), re-installed at session desktop-ensure by the
+ * server (persistent.ts), and written by the browser backfill right after it
+ * lands chromium on a grandfathered image — so a backfilled browser behaves
+ * exactly like a baked one. Before this, a backfilled chromium had NO flags
+ * file: a root launch died on the missing --no-sandbox ("exited
+ * immediately"), and every launch paid the first-run wizard.
+ *
+ * Debian's /usr/bin/chromium wrapper dot-sources every /etc/chromium.d/*
+ * fragment, so these flags apply to EVERY door into the browser — the dock
+ * launcher, the openbox menu, ac-open, an agent's bare `chromium`.
+ *
+ * Flag notes:
+ *   --disable-gpu — the session display is Xkasmvnc, which exposes NO GLX
+ *     (probe-verified in a live sandbox, 2026-08-21). Without the flag,
+ *     chromium's GPU process walks both EGL display types (OpenGL, then
+ *     OpenGLES) through ANGLE, fails both ("Initialization of all (2) EGL
+ *     display types failed"), respawns, and only then falls back to the
+ *     software raster it was always going to use — measured at 200-500ms of
+ *     pure startup waste per launch on an idle host, worse on a shared
+ *     2-vCPU guest. Software WebGL (SwiftShader) still works.
+ *   --disable-session-crashed-bubble — a paused/killed VM otherwise greets
+ *     every reattach with the restore bubble.
+ *   --no-sandbox only under root — chromium refuses to start as root
+ *     without it; the per-session microVM is the isolation boundary.
+ */
+export const CHROMIUM_DEFAULTS_PATH = "/etc/chromium.d/00-ac-defaults";
+
+export const CHROMIUM_DEFAULTS = `# agent-compose session-desktop chromium defaults
+# (single-sourced in sdk/src/agent/desktop-open.ts — sourced by /usr/bin/chromium)
+CHROMIUM_FLAGS="$CHROMIUM_FLAGS --no-first-run --no-default-browser-check --password-store=basic --disable-session-crashed-bubble --disable-dev-shm-usage --start-maximized --disable-gpu"
+if [ "$(id -u)" = "0" ]; then CHROMIUM_FLAGS="$CHROMIUM_FLAGS --no-sandbox"; fi
+`;
+
+/**
+ * Install (or refresh) the chromium defaults fragment — run as root.
+ * QUOTE-FREE by construction (base64 payload, no quoting anywhere): the
+ * string embeds verbatim inside browserBackfillCmd's single-quoted `sh -c`
+ * payload as well as standing alone in a template runCmd / an ensure exec.
+ */
+export function installChromiumDefaultsCmd(): string {
+  const b64 = Buffer.from(CHROMIUM_DEFAULTS, "utf8").toString("base64");
+  return [
+    "mkdir -p /etc/chromium.d",
+    `printf %s ${b64} | base64 -d > ${CHROMIUM_DEFAULTS_PATH}`,
+    `chmod 0644 ${CHROMIUM_DEFAULTS_PATH}`,
+    `sh -n ${CHROMIUM_DEFAULTS_PATH}`,
+  ].join(" && ");
+}
+
+/**
+ * Probe-then-heal for the browser on a GRANDFATHERED image — run as root at
+ * session desktop-ensure (server/src/sandbox/attach/browser-backfill.ts).
+ *
+ * Scope is exactly chromium, deliberately not a package set: every desktop
+ * bake since the first (8329c9c4) hard-installs xdotool/scrot/pcmanfm in the
+ * SAME `&&`-joined apt line as the desktop stack itself, so any image that
+ * probes a desktop necessarily carries them — chromium alone rode a tolerant
+ * `|| true` until the 2026-08-16 hard-install, making it the only
+ * manual-promised desktop tool that can be missing. (ac-open and ac-record
+ * are re-installed on every fresh boot by ensureSessionDesktop already.)
+ *
+ * Shape: a three-way verdict on stdout (the desktop-capability-probe idiom —
+ * `backfill=present` / `backfill=in-progress` / `backfill=started`), and on
+ * `started` the apt install runs DETACHED — `setsid … </dev/null >>log 2>&1 &`
+ * plus a pidfile, the exact ac-open/cli-agent discipline — so this command
+ * returns in milliseconds while apt takes its 20-40s. Single-flight is the
+ * pidfile liveness gate (a second ensure sees `in-progress` and starts
+ * nothing); apt's own dpkg lock backstops the millisecond race window. The
+ * installer's last act is its verdict: a failure touches the `.failed` marker
+ * (cause in the log) and either way the pidfile is removed, so a machine
+ * suspended mid-install simply retries on its next fresh boot.
+ */
+export function browserBackfillCmd(): string {
+  const pid = BROWSER_BACKFILL_PIDFILE;
+  // The defaults install rides INSIDE the success chain: a backfilled
+  // chromium without its flags fragment still crashes every root launch
+  // (missing --no-sandbox — the 2026-08-21 transcript's other half), so a
+  // browser without flags is a failed heal, reported as one.
+  // installChromiumDefaultsCmd() is quote-free by construction, so it embeds
+  // verbatim in this single-quoted payload.
+  return (
+    `mkdir -p ${AC_OPEN_STATE_DIR} && ` +
+    `if command -v chromium >/dev/null 2>&1; then echo backfill=present; ` +
+    `elif [ -f ${pid} ] && kill -0 "$(cat ${pid} 2>/dev/null)" 2>/dev/null; then echo backfill=in-progress; ` +
+    `else rm -f ${BROWSER_BACKFILL_FAILED}; ` +
+    `setsid sh -c 'if apt-get update -q && DEBIAN_FRONTEND=noninteractive apt-get install -y -q chromium && command -v chromium >/dev/null 2>&1 && ${installChromiumDefaultsCmd()}; then echo backfill-install=ok; else echo backfill-install=failed; touch ${BROWSER_BACKFILL_FAILED}; fi; rm -f ${pid}' </dev/null >>${BROWSER_BACKFILL_LOG} 2>&1 & ` +
+    `echo $! > ${pid}; echo backfill=started; fi`
+  );
+}
+
+/**
+ * The watcher's status probe (read-only, safe from any user): `backfill=ok` /
+ * `backfill=failed` (+ the log tail as the cause, one line) /
+ * `backfill=in-progress` / `backfill=lost` (installer died without a verdict
+ * — suspend/recycle mid-apt; the next fresh boot's ensure retries).
+ */
+export function browserBackfillStatusCmd(): string {
+  return (
+    `if command -v chromium >/dev/null 2>&1; then echo backfill=ok; ` +
+    `elif [ -f ${BROWSER_BACKFILL_FAILED} ]; then echo backfill=failed; tail -c 300 ${BROWSER_BACKFILL_LOG} 2>/dev/null | tr '\\n' ' '; ` +
+    `elif [ -f ${BROWSER_BACKFILL_PIDFILE} ] && kill -0 "$(cat ${BROWSER_BACKFILL_PIDFILE} 2>/dev/null)" 2>/dev/null; then echo backfill=in-progress; ` +
+    `else echo backfill=lost; fi`
+  );
+}

package/src/agent/perf-sampler.ts

@@ -0,0 +1,202 @@
+/**
+ * Guest-side session perf sampling — the `<promptPath>.perf` token contract.
+ *
+ * The session guest has NO push channel: every durable signal is a flat file
+ * next to the turn's prompt path, read by bounded server execs (the durable
+ * trio — see tailer.ts / _cli-agent.ts). Perf sampling rides that exact
+ * plane:
+ *
+ *   - LIVE turn: the runner's 10s heartbeat subshell calls `ac_perf_tick`
+ *     each beat; every 6th beat (~60s) it burst-reads /proc (stat jiffies
+ *     delta, loadavg, meminfo) plus one `df -P`, and rewrites the perf
+ *     token file atomically. The subshell dies with the wrapper, so
+ *     sampling stops within one beat of turn end — it can never keep the
+ *     setsid group alive (the 2026-08-17 spurious-wake class).
+ *   - The token then rides the EXISTING durable-trio probe exec as one
+ *     trailing field (`turnLivenessProbeCommand`) — no new exec, no new
+ *     socket, ~70 extra bytes on a line the server already pulls.
+ *   - PARKED-AWAKE: the server's 5-min compute-span checkpoint (which
+ *     already holds the provider's RUNNING list — a suspended machine is
+ *     structurally never probed) runs `standalonePerfProbeCommand`: the
+ *     same read burst twice across a short window, one bounded exec.
+ *
+ * Token format (ONE whitespace-free field, so it can ride a space-split
+ * probe line): `v=1,cpu=12,l1=0.42,mem=37,dsk=52,vc=2,ram=4096,ts=1755…`
+ *   cpu  — busy % of all vcpus over the sampling window (-1 = no window yet)
+ *   l1   — 1-min loadavg (-1 = unreadable)
+ *   mem  — used % of MemTotal, via MemAvailable (-1 = unreadable)
+ *   dsk  — used % of the root filesystem (-1 = unreadable)
+ *   vc   — vcpu count (cpuN lines in /proc/stat)
+ *   ram  — MemTotal in MB (the sandbox-size context the fold tags by)
+ *   ts   — guest clock, epoch seconds (dedupe only, never arithmetic)
+ *
+ * The guest is hostile by doctrine (registry-activities.ts house rule):
+ * `parsePerfToken` clamps every field to its closed range and nulls
+ * anything out of bounds — server folds re-use this parser, so no guest
+ * number reaches a metric or a Temporal payload unclamped.
+ */
+
+import { shellQuote } from "../runtimes/_cli-agent.js";
+
+/** Sample every Nth heartbeat beat (10s beats → ~60s cadence). */
+export const PERF_SAMPLE_EVERY_BEATS = 6;
+
+/** CPU window of the standalone (parked-awake) probe, seconds. */
+export const PERF_PROBE_WINDOW_SECONDS = 2;
+
+/** The standalone probe's output line leads with this prefix. */
+export const PERF_PROBE_LINE_PREFIX = "perf ";
+
+/** Longest token the parsers accept — anything bigger is garbage. */
+export const PERF_TOKEN_MAX_CHARS = 200;
+
+/** One clamped guest perf sample. Null fields = unreadable/absent on the
+ *  guest — never zero-filled (a zero is a claim; null is honesty). */
+export interface GuestPerfSample {
+  /** Busy % of all vcpus over the sample window, 0–100. */
+  cpuBusyPct: number | null;
+  /** 1-minute load average. */
+  load1: number | null;
+  /** Used % of MemTotal (MemAvailable-based), 0–100. */
+  memUsedPct: number | null;
+  /** Used % of the root filesystem, 0–100. */
+  diskUsedPct: number | null;
+  /** vcpu count — the sandbox-size context tag. */
+  vcpus: number | null;
+  /** MemTotal in MB — the other half of the size context. */
+  ramMb: number | null;
+  /** Guest clock at sample time, epoch seconds. Dedupe only. */
+  sampledAtS: number | null;
+}
+
+export interface PerfSamplerPaths {
+  /** Durable token file (`<promptPath>.perf`). */
+  perfPath: string;
+  /** Override for tests ONLY — fixture dir standing in for /proc. */
+  procRoot?: string;
+  /** Filesystem to `df` (default "/"). */
+  diskPath?: string;
+}
+
+/**
+ * POSIX-sh function definitions for the read burst. `ac_perf_read` reads
+ * /proc once, computes the jiffies delta against the PREVIOUS call (state
+ * lives in shell variables — the heartbeat subshell persists across beats,
+ * so no state file), and leaves the finished token in `$ac_tok`. All
+ * `ac_p*` variable names are prefixed to stay clear of the loop's own
+ * `ac_busy` / `ac_idle` vocabulary.
+ *
+ * Every read is `2>/dev/null`-guarded and every field degrades to -1 — a
+ * missing /proc entry can never wedge the heartbeat loop.
+ */
+function perfReadFunctionFragment(procRoot: string, diskPath: string): string {
+  const stat = shellQuote(`${procRoot}/stat`);
+  const loadavg = shellQuote(`${procRoot}/loadavg`);
+  const meminfo = shellQuote(`${procRoot}/meminfo`);
+  const disk = shellQuote(diskPath);
+  return `ac_perf_read() { `
+    // cpu line: user nice system idle iowait irq softirq steal …
+    + `IFS=' ' read -r ac_pl ac_pu ac_pn2 ac_psy ac_pid ac_pio ac_pirq ac_psq ac_pst ac_prest 2>/dev/null < ${stat} || return 0; `
+    + `ac_pbz=$(( \${ac_pu:-0} + \${ac_pn2:-0} + \${ac_psy:-0} + \${ac_pirq:-0} + \${ac_psq:-0} + \${ac_pst:-0} )); `
+    + `ac_ptt=$(( ac_pbz + \${ac_pid:-0} + \${ac_pio:-0} )); `
+    + `ac_pcpu=-1; `
+    + `if [ "\${ac_ppt:-0}" -gt 0 ] && [ "$ac_ptt" -gt "\${ac_ppt:-0}" ]; then `
+    + `ac_pcpu=$(( 100 * (ac_pbz - \${ac_ppb:-0}) / (ac_ptt - ac_ppt) )); `
+    + `[ "$ac_pcpu" -lt 0 ] && ac_pcpu=0; [ "$ac_pcpu" -gt 100 ] && ac_pcpu=100; `
+    + `fi; `
+    + `ac_ppb=$ac_pbz; ac_ppt=$ac_ptt; `
+    + `IFS=' ' read -r ac_pl1 ac_plr 2>/dev/null < ${loadavg} || ac_pl1=-1; `
+    + `ac_pvc=$(grep -c '^cpu[0-9]' ${stat} 2>/dev/null); [ -n "$ac_pvc" ] || ac_pvc=0; `
+    + `ac_pmt=$(awk '$1=="MemTotal:"{print $2}' ${meminfo} 2>/dev/null); `
+    + `ac_pma=$(awk '$1=="MemAvailable:"{print $2}' ${meminfo} 2>/dev/null); `
+    + `ac_pmem=-1; `
+    + `if [ "\${ac_pmt:-0}" -gt 0 ] && [ -n "\${ac_pma:-}" ]; then ac_pmem=$(( 100 * (ac_pmt - ac_pma) / ac_pmt )); fi; `
+    + `[ "$ac_pmem" -gt 100 ] && ac_pmem=100; [ "$ac_pmem" -lt -1 ] && ac_pmem=-1; `
+    + `ac_pdsk=$(df -kP ${disk} 2>/dev/null | awk 'NR==2 && $2>0 {print int(100*$3/$2)}'); `
+    + `ac_tok="v=1,cpu=$ac_pcpu,l1=\${ac_pl1:--1},mem=$ac_pmem,dsk=\${ac_pdsk:--1},vc=\${ac_pvc:-0},ram=$(( \${ac_pmt:-0} / 1024 )),ts=$(date +%s)"; `
+    + `}; `;
+}
+
+/**
+ * The heartbeat-loop member: function definitions plus `ac_perf_tick`,
+ * which gates the burst to every `PERF_SAMPLE_EVERY_BEATS`th beat (beat 1
+ * establishes the jiffies baseline — its token carries cpu=-1; beat 7 is
+ * the first real cpu window) and rewrites the token file atomically
+ * (tmp + `mv -f`, so a concurrent probe `head` reads old-or-new, never a
+ * torn write). Place the returned fragment INSIDE the heartbeat subshell,
+ * before its `while`; call `ac_perf_tick` once per beat in the body.
+ */
+export function perfSamplerFunctionFragment(paths: PerfSamplerPaths): string {
+  const perf = shellQuote(paths.perfPath);
+  const perfTmp = shellQuote(`${paths.perfPath}.tmp`);
+  return perfReadFunctionFragment(paths.procRoot ?? "/proc", paths.diskPath ?? "/")
+    + `ac_perf_tick() { `
+    + `ac_pbeat=$(( \${ac_pbeat:-0} + 1 )); `
+    + `[ $(( (ac_pbeat - 1) % ${PERF_SAMPLE_EVERY_BEATS} )) -eq 0 ] || return 0; `
+    + `ac_perf_read; `
+    + `[ -n "\${ac_tok:-}" ] || return 0; `
+    + `printf '%s\\n' "$ac_tok" > ${perfTmp} 2>/dev/null && mv -f ${perfTmp} ${perf} 2>/dev/null; `
+    + `}; `;
+}
+
+/**
+ * Self-contained one-exec probe for the parked-awake lane (the server's
+ * 5-min compute-span checkpoint): two read bursts across a short window
+ * give a real cpu delta, then the token prints to stdout as
+ * `perf <token>`. Bounded by the caller's exec timeout; ~window+ε runtime.
+ */
+export function standalonePerfProbeCommand(opts: {
+  procRoot?: string; diskPath?: string; windowSeconds?: number;
+} = {}): string {
+  const win = opts.windowSeconds ?? PERF_PROBE_WINDOW_SECONDS;
+  return perfReadFunctionFragment(opts.procRoot ?? "/proc", opts.diskPath ?? "/")
+    + `ac_perf_read; sleep ${win}; ac_perf_read; `
+    + `printf '${PERF_PROBE_LINE_PREFIX}%s\\n' "\${ac_tok:--}"`;
+}
+
+/** Parse + CLAMP one perf token. Null = no usable sample (absent file, a
+ *  garbled write, a hostile guest). Out-of-range fields null out
+ *  individually; a token with no usable utilization field at all is null. */
+export function parsePerfToken(token: string): GuestPerfSample | null {
+  const t = token.trim();
+  if (t.length === 0 || t.length > PERF_TOKEN_MAX_CHARS) return null;
+  if (!/^v=1(?:,|$)/.test(t)) return null;
+  const kv = new Map<string, string>();
+  for (const part of t.split(",")) {
+    const i = part.indexOf("=");
+    if (i > 0) kv.set(part.slice(0, i), part.slice(i + 1));
+  }
+  const pct = (k: string): number | null => {
+    const n = Number(kv.get(k));
+    return Number.isFinite(n) && n >= 0 && n <= 100 ? Math.round(n) : null;
+  };
+  const bounded = (k: string, min: number, max: number): number | null => {
+    const n = Number(kv.get(k));
+    return Number.isInteger(n) && n >= min && n <= max ? n : null;
+  };
+  const l1raw = Number(kv.get("l1"));
+  const sample: GuestPerfSample = {
+    cpuBusyPct: pct("cpu"),
+    load1: Number.isFinite(l1raw) && l1raw >= 0 && l1raw <= 100_000 ? l1raw : null,
+    memUsedPct: pct("mem"),
+    diskUsedPct: pct("dsk"),
+    vcpus: bounded("vc", 1, 1024),
+    ramMb: bounded("ram", 1, 16 * 1024 * 1024),
+    // Bounded to [2020, 2100) in epoch seconds — dedupe-grade only.
+    sampledAtS: bounded("ts", 1_577_836_800, 4_102_444_800),
+  };
+  if (sample.cpuBusyPct === null && sample.load1 === null
+    && sample.memUsedPct === null && sample.diskUsedPct === null) return null;
+  return sample;
+}
+
+/** Parse the standalone probe's stdout (the LAST `perf ` line wins — envd
+ *  occasionally prepends shell noise). */
+export function parsePerfProbeOutput(stdout: string): GuestPerfSample | null {
+  const lines = stdout.split("\n").filter((l) => l.startsWith(PERF_PROBE_LINE_PREFIX));
+  const last = lines[lines.length - 1];
+  if (!last) return null;
+  const token = last.slice(PERF_PROBE_LINE_PREFIX.length).trim();
+  if (token === "-") return null;
+  return parsePerfToken(token);
+}