@agent-compose/sdk 0.8.1 → 0.8.3

package/src/agent/agent-context.ts

@@ -145,27 +145,81 @@ like?" is answered by opening it on this desktop and screenshotting it — not b
 reasoning about the code, and not by a headless render (which proves the process
 starts, not that the thing draws). Verify visually before you report visually.
 
+**This is how you ACT on the web.** When the task is to DO something on a
+website — book, order, reserve, sign up, fill a form, operate a dashboard —
+and no connector or API covers it, the desktop browser IS the tool: \`ac-open\`
+the site, do the errand there, and show the human the screen at decision
+points (\`agentc display desktop\` in a cloud session). Research/search tools
+answer QUESTIONS; an errand is an ACTION — "book me a table" means open the
+booking site and book it, never a research report of options.
+
 - **Input** — \`xdotool\` against \`DISPLAY=:0\`: \`DISPLAY=:0 xdotool mousemove <x> <y>\`,
   \`DISPLAY=:0 xdotool click 1\` (1=left, 3=right), \`DISPLAY=:0 xdotool type 'text'\`,
   \`DISPLAY=:0 xdotool key Return\` (also \`ctrl+c\`, \`Tab\`, \`super\`, …).
 - **Screenshots** — \`scrot\` (or ImageMagick's \`import\`):
   \`DISPLAY=:0 scrot /tmp/screen.png\`, then READ the PNG to see the screen,
   before and after you act. A screenshot is your only eyes here.
-- **Apps + windows** — a plain X session. Launch in the background:
-  \`DISPLAY=:0 <app> &\`. Two things that trip agents up, both normal:
+- **The browser is chromium, preinstalled** — headful, on this display
+  (\`command -v chromium\` to confirm on an older machine). If an older machine
+  is missing it, the platform is already installing it in the background from
+  boot — \`ac-open <url>\` tells you when that is the case; retry it in ~30s.
+  Only if \`ac-open\` reports the background install FAILED do you relay that
+  one line to the human — never an apt-get expedition of your own.
+- **Launching apps — use \`ac-open\`, never a plain \`&\`.** A GUI process
+  launched with \`<app> &\` DIES the moment your shell command returns — the
+  sandbox reaps each command's process group, so "the window vanished when
+  the shell finished" is that reaping, not a broken app. \`ac-open\` is the
+  platform launcher that survives it (\`command -v ac-open\` on older machines):
+
+      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                   # any GUI app by command name
+
+  It detaches the app into its own session (setsid, stdio off your command's
+  pipes), records a pidfile + log under \`/tmp/.ac-desktop-open.<uid>/\`
+  (per-uid — yours is \`/tmp/.ac-desktop-open.$(id -u)\`), and
+  re-invoking it for a running app FOCUSES the existing window instead of
+  spawning a second copy. \`xdg-open\` and \`sensible-browser\` route through
+  it too. The whole recipe for looking at a page: \`ac-open <url>\`, then
+  \`sleep 5\`, then \`DISPLAY=:0 scrot /tmp/screen.png\` and read it. Without
+  \`ac-open\` (older machine), detach by hand:
+  \`setsid <app> </dev/null >/tmp/app.log 2>&1 &\` — and note **chromium as
+  root also needs \`--no-sandbox\`** (nested sandbox; \`ac-open\` and the baked
+  chromium defaults already handle it).
+- **Two things that trip agents up, both normal:**
   - a GUI app needs a **beat to map its window** — screenshot, and if you see
     only wallpaper, wait a couple of seconds and screenshot again before
     concluding anything;
-  - **Chromium needs \`--no-sandbox\`** in this environment (nested sandbox).
-    The whole recipe for looking at a local page:
-    \`DISPLAY=:0 chromium --no-sandbox --disable-gpu --start-maximized <url> &\`
-    then \`sleep 5\`, then \`DISPLAY=:0 scrot /tmp/screen.png\` and read it.
-  If a window still never appears, read the app's own log (\`/tmp/*.log\`) — the
-  desktop is not the thing that failed. Do NOT abandon it for a headless
-  screenshot: headless cannot tell you what the human will see.
+  - if a window still never appears, read the app's own log
+    (\`/tmp/.ac-desktop-open.$(id -u)/*.log\`, \`/tmp/*.log\`) — the desktop is not the
+    thing that failed. Do NOT abandon it for a headless
+    screenshot: headless cannot tell you what the human will see.
 - **A human can watch** — the session header carries a **Desktop** button in the
   dashboard, and what a teammate sees there is exactly this display. The desktop
   runs whether or not anyone is looking; never wait for a viewer.
+- **Show the human the screen** — in a cloud session,
+  \`agentc display desktop --note "<caption>"\` captures this display and posts
+  it into the conversation as a snapshot card with an "Open desktop" door to
+  the live view. Use it to report visual results, and ALWAYS when you hit a
+  wall on the desktop that only a human can clear — a login form, a 2FA
+  prompt, a CAPTCHA, an unexpected dialog: snapshot it so they SEE the wall,
+  then ask (AskUserQuestion when you have it) and wait; never guess
+  credentials or click around a wall. The rule is SCREEN FOR ACTIONS,
+  VAULT FOR SECRETS. For non-sensitive interaction that needs the human's
+  own hands or judgment — pick an option, review a page, solve a CAPTCHA —
+  the display + ask pair is right: the platform merges them into ONE live
+  desktop card — the human clicks in, acts on the live screen, and answers
+  "I'm done" to hand it back; treat that answer as the wall being cleared,
+  re-check the screen, and continue. For SECRETS — a password, payment
+  details, any sensitive value —
+  \`agentc secrets session request <KEY...> --reason "<why>" --wait\` mints a
+  secure vault link (a one-tap approval when the user has these saved as a
+  personal set); the values land in the session env and YOU type them into
+  the site on the user's behalf. Never ask the human to type a password or
+  card number into this machine's browser, and never suggest they "log in
+  on the Desktop view" — the vault carries the secret, then you act with
+  it. A one-time 2FA code from their phone is the chat-OK exception.
 
 Nothing here changes the credentials rule above: tokens are injected at the
 network layer, never present on the desktop or in any file you can read — so
@@ -173,38 +227,49 @@ there is nothing to type, paste, or screenshot a credential from.
 
 ## Recording a demo — the desktop, captured to a video the human can play
 
-"Record a demo of you using X" is a normal ask, and this machine does it:
-start a screen recording, drive the app with \`xdotool\` exactly as in Computer
-Use, stop the recording, and report the file. (For a LIVE view no recording is
-needed — the session header's **Desktop** button already streams this display
-to any teammate watching; a recording is the durable, replayable artifact.
-Both modes exist; say so when it matters.)
+"Record a demo of you using X" is a normal ask, and this machine does it.
+(For a LIVE view no recording is needed — the session header's **Desktop**
+button already streams this display to any teammate watching; a recording is
+the durable, replayable artifact. Both modes exist; say so when it matters.)
+
+**Use \`ac-record\` — the platform recorder is already on PATH** (cloud
+sessions; \`command -v ac-record\` to confirm on older machines):
 
-**ffmpeg is NOT pre-installed** — install it first, once per machine:
+    ac-record start     # begins capturing the desktop (display :0)
+    # ... drive the app with xdotool, screenshotting as you go ...
+    ac-record stop      # finishes + saves to recordings/ in your workspace
+    ac-record status    # one JSON line: {"recording":true,...}
 
-    sudo apt-get update -q && sudo apt-get install -y -q ffmpeg
+It records the whole display (with desktop audio when the machine has a
+PulseAudio monitor), enforces sane caps (5 min / 200 MB — start a fresh
+recording per scene rather than one long take), keeps the file playable even
+if the machine dies mid-take, and \`stop\` prints the saved path — the file
+lands ON THE DRIVE in \`recordings/\`, visible in Files and playable in the
+dashboard. A human watching the Desktop pane sees the recording indicator
+while you record.
 
-(drop \`sudo\` if you are already root). Then the whole recipe:
+If \`ac-record\` is missing (older machine), record by hand.
+**ffmpeg IS pre-installed** on platform images (\`command -v ffmpeg\`; only
+if absent: \`sudo apt-get update -q && sudo apt-get install -y -q ffmpeg\`):
 
     DISPLAY=:0 ffmpeg -f x11grab \\
       -video_size "$(DISPLAY=:0 xdotool getdisplaygeometry | tr ' ' x)" \\
       -framerate 10 -i :0 -c:v libvpx -b:v 1M -deadline realtime -cpu-used 8 \\
       demo.webm &
     FFMPEG_PID=$!
-    # ... drive the app with xdotool, screenshotting as you go ...
+    # ... drive the app with xdotool ...
     kill -INT "$FFMPEG_PID" && wait "$FFMPEG_PID"
 
-The gotchas, each one earned:
+The hand-rolled gotchas, each one earned:
 - **Stop with SIGINT (\`kill -INT\`), never SIGKILL** — ffmpeg finalizes the
   file on SIGINT; a hard kill truncates the encode mid-write.
-- **Record WebM (matroska-family), not MP4** — mp4 writes its moov atom at the
-  END, so a killed or crashed encode leaves an UNPLAYABLE file; webm stays
-  playable up to the last written frame and plays natively in the browser.
-  MP4's only edge is compatibility with some external players — transcode
-  afterwards if you truly need it, never record straight to it.
+- **Record WebM (matroska-family), not plain MP4** — mp4 writes its moov atom
+  at the END, so a killed or crashed encode leaves an UNPLAYABLE file; webm
+  stays playable up to the last written frame and plays natively in the
+  browser. (\`ac-record\` sidesteps this with fragmented mp4.)
 - **\`-video_size\` must match the real screen** — x11grab does not default to
   it; read the geometry from \`xdotool getdisplaygeometry\` as above.
-- **10–12 fps is right for a screen demo** — small files, legible UI motion;
+- **10–15 fps is right for a screen demo** — small files, legible UI motion;
   this is not video production.
 - **Write to the drive, not /tmp** — the recording must land in your working
   directory to persist and show up in Files; a file in /tmp dies with the
@@ -245,14 +310,49 @@ origin of its own — absolute asset paths and client-side routing work, the
 whole app is navigable — so serve normally and let the platform address it;
 never rewrite your app to a path prefix.
 
+## Durable services — the machine is cattle, the manifest is the pet (cloud sessions)
+
+Parking preserves detached processes; a machine RECYCLE (resize, eviction,
+failed reconnect) does not — every process and every byte off the drive is
+discarded, and recycles are normal. When you start a long-running service the
+human will rely on across turns (a dev server, a docker compose stack, a
+database), record it in \`.ac/services.yml\` at the drive root so the platform
+relaunches it automatically on the next fresh machine:
+
+    agentc services add <name> --command '<cmd>'   # record a service
+    agentc services list                           # manifest + live status
+    agentc services restore                        # run the manifest now
+    agentc services remove <name>
+
+Each entry can carry \`cwd\`, \`port\`, a bounded \`health\` probe (cmd or
+http), one-time \`setup\` (e.g. \`docker compose pull\`), and \`data\` hooks.
+After a recycle the platform posts "Machine restarted — restored N services"
+into the conversation; on seeing it, VERIFY health rather than rebuilding —
+logs live at \`/tmp/ac-services/<name>.log\`. Data honesty: sandbox-local
+database state dies with the machine. Keep seeds/dumps ON THE DRIVE; declare
+\`data.restore\` (reload on fresh boot) and \`data.dump\` (written before a
+DELIBERATE recycle such as a resize — evictions give no warning, so treat the
+drive copy as the truth).
+
 ## Tools in this environment
 
 - \`agentc\` — Agent Compose CLI (your primary interface; authed from env)
 - \`@agent-compose/sdk\` — installed in /workspace for writing workflows
 - \`/ac:*\` Claude Code skills — slash commands for the above
-- \`archil\` (factory drive), \`rtk\`, \`bun\`
+- \`rtk\`, \`bun\`
 - \`xdotool\` / \`scrot\` — drive + screenshot the desktop (if this machine has one; see Computer Use)
-- A world-writable \`/workspace\` working directory`;
+- \`chromium\` — the desktop browser; \`ac-open <url|file|app>\` — open it on the
+  desktop, detached (survives your command; see Computer Use)
+- A world-writable \`/workspace\` working directory
+
+If a system capability you need is genuinely missing — no browser, no display,
+no \`ac-open\`, a daemon that isn't there — say so to the human in ONE honest
+line (what is missing and what it blocks) instead of mounting a
+package-manager expedition. An in-session \`apt-get install\` dies with the
+sandbox, burns turns, and hides the real gap; missing platform capabilities
+are the platform's to bake in, and \`agentc pause\` is the door to ask through.
+(Your own project's dependencies are different — installing those is normal
+work.)`;
 
 /** Parameters for the `agentc session add` education brief (ADR-0055 §8). */
 export interface AddedSessionBriefParams {

package/src/agent/agent-loop.ts

@@ -91,8 +91,13 @@ function preview(value: unknown): string {
 
 /** Everything but the live-only streaming chunk: `text_delta` never becomes
  *  an agent.message event (the terminating `text` carries the whole block) —
- *  the loop filters it before summarizing. */
-type DurableAgentMessage = Exclude<AgentMessage, { type: "text_delta" } | { type: "usage_delta" }>;
+ *  the loop filters it before summarizing. `task_notification` is filtered
+ *  too: it is session-transport metadata (a parent harness's background-task
+ *  completion echo), not the agent's own output. */
+type DurableAgentMessage = Exclude<
+  AgentMessage,
+  { type: "text_delta" } | { type: "usage_delta" } | { type: "task_notification" }
+>;
 
 export function summarizeAgentMessage(msg: DurableAgentMessage): AgentMessageSummary {
   switch (msg.type) {
@@ -478,7 +483,9 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
         continue;
       }
       const msg = outputVerdict.value;
-      if (msg.type === "text_delta" || msg.type === "usage_delta") continue; // a processor cannot re-introduce a live-only chunk
+      // A processor cannot re-introduce a live-only chunk; task
+      // notifications are transport metadata, never loop output.
+      if (msg.type === "text_delta" || msg.type === "usage_delta" || msg.type === "task_notification") continue;
       opts.onAgentEvent?.(iteration, msg);
       // Usage summaries carry the resolved model so the server can price
       // token rows per model without correlating back to agent.spawned.

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`
+  );
+}