@agent-compose/sdk 0.8.2 → 0.8.4

package/dist/index.js

@@ -1608,6 +1608,9 @@ class AgentComposeClient {
   async getRunFunding(runId) {
     return this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/funding`);
   }
+  async getRunStepUsage(runId) {
+    return this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/step-usage`);
+  }
   async reportEvent(runId, input) {
     const body = {
       ...input,
@@ -1663,6 +1666,8 @@ class AgentComposeClient {
       q2.set("revision", String(opts.revision));
     if (opts?.branch !== undefined)
       q2.set("branch", opts.branch);
+    if (opts?.at !== undefined)
+      q2.set("at", opts.at);
     const buf = await this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/files/content?${q2}`, { responseType: "arrayBuffer" });
     return new Uint8Array(buf);
   }
@@ -1695,6 +1700,22 @@ class AgentComposeClient {
       q2.set("cursor", opts.cursor);
     return this.fetch(`/api/v1/sessions?${q2}`);
   }
+  getSessionPerfHistory(conversationId, opts) {
+    const q2 = new URLSearchParams;
+    if (opts?.limit !== undefined)
+      q2.set("limit", String(opts.limit));
+    if (opts?.cursor)
+      q2.set("cursor", opts.cursor);
+    return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/perf-history${q2.toString() ? `?${q2}` : ""}`);
+  }
+  getFactoryPerfSummary(factorySlug, opts) {
+    const q2 = new URLSearchParams;
+    if (opts?.from)
+      q2.set("from", opts.from);
+    if (opts?.to)
+      q2.set("to", opts.to);
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/perf-summary${q2.toString() ? `?${q2}` : ""}`);
+  }
   getConversation(id, opts) {
     const q2 = opts?.limit !== undefined ? `?limit=${opts.limit}` : "";
     return this.fetch(`/api/v1/conversations/${encodeURIComponent(id)}${q2}`);
@@ -1738,6 +1759,27 @@ class AgentComposeClient {
   postSessionChannelMessage(channelId, input) {
     return this.fetch(`/api/v1/conversations/${encodeURIComponent(channelId)}/session-messages`, { method: "POST", body: { text: input.text, ...input.threadRootId ? { threadRootId: input.threadRootId } : {} } });
   }
+  sendSessionMessage(input) {
+    return this.fetch("/api/v1/session-messages", {
+      method: "POST",
+      body: input
+    });
+  }
+  claimSessionBranch(input) {
+    return this.fetch("/api/v1/session-branch-claims", {
+      method: "POST",
+      body: { target: input.target, ...input.reason ? { reason: input.reason } : {} }
+    });
+  }
+  releaseSessionBranchClaims(input = {}) {
+    return this.fetch("/api/v1/session-branch-claims/release", {
+      method: "POST",
+      body: { ...input.target ? { target: input.target } : {} }
+    });
+  }
+  getSessionBranchClaimState(conversationId) {
+    return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/branch-claim`);
+  }
   openPreview(conversationId, input) {
     return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/preview`, {
       method: "POST",
@@ -1766,8 +1808,33 @@ class AgentComposeClient {
   forkSession(conversationId, input) {
     return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/fork`, { method: "POST", body: input?.title ? { title: input.title } : {} });
   }
-  getSessionChanges(conversationId) {
-    return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/changes`);
+  getSessionChanges(conversationId, opts = {}) {
+    const q2 = new URLSearchParams;
+    if (opts.after !== undefined)
+      q2.set("after", opts.after);
+    if (opts.limit !== undefined)
+      q2.set("limit", String(opts.limit));
+    const tail = q2.toString();
+    return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/changes${tail ? `?${tail}` : ""}`);
+  }
+  async getSessionChangeContent(conversationId, path, opts = {}) {
+    const q2 = new URLSearchParams({ path });
+    if (opts.side !== undefined)
+      q2.set("side", opts.side);
+    const buf = await this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/changes/content?${q2}`, { responseType: "arrayBuffer" });
+    return new Uint8Array(buf);
+  }
+  publishReviewNotes(conversationId, input) {
+    return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/review-notes`, {
+      method: "POST",
+      body: {
+        notes: input.notes,
+        ...input.suggestions !== undefined ? { suggestions: input.suggestions } : {}
+      }
+    });
+  }
+  getReviewGitCredential(conversationId) {
+    return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/review-git-credential`, { method: "POST" });
   }
   mergeSessionChanges(conversationId, opts = {}) {
     return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/changes/merge`, { method: "POST", body: opts.branch ? { branch: opts.branch } : {} });
@@ -1775,6 +1842,15 @@ class AgentComposeClient {
   discardSessionChanges(conversationId, opts = {}) {
     return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/changes/discard`, { method: "POST", body: opts.branch ? { branch: opts.branch } : {} });
   }
+  getSessionChangePreflight(conversationId) {
+    return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/changes/preflight`);
+  }
+  rebaseSessionChanges(conversationId, opts = {}) {
+    return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/changes/rebase`, { method: "POST", body: opts.branch ? { branch: opts.branch } : {} });
+  }
+  setSessionAutoRebase(conversationId, enabled) {
+    return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/changes/autorebase`, { method: "POST", body: { enabled } });
+  }
   async getConversationMembers(conversationId) {
     const body = await this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/members`);
     return body.members;
@@ -1829,6 +1905,28 @@ class AgentComposeClient {
       q2.set("cursor", opts.cursor);
     return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/files/search?${q2}`);
   }
+  async listFactoryFiles(opts) {
+    const factorySlug = opts?.factorySlug ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined) ?? DEFAULT_FACTORY;
+    const q2 = new URLSearchParams;
+    if (opts?.prefix)
+      q2.set("prefix", opts.prefix);
+    if (opts?.cursor)
+      q2.set("cursor", opts.cursor);
+    if (opts?.limit != null)
+      q2.set("limit", String(opts.limit));
+    if (opts?.branch !== undefined)
+      q2.set("branch", opts.branch);
+    if (opts?.at !== undefined)
+      q2.set("at", opts.at);
+    const qs = q2.toString();
+    const wire = await this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/files${qs ? `?${qs}` : ""}`);
+    return {
+      data: wire.data,
+      hasMore: wire.has_more,
+      nextCursor: wire.next_cursor,
+      at: wire.at ? { head: wire.at.head, committedAt: wire.at.committed_at } : null
+    };
+  }
   async listMembers() {
     const body = await this.fetch("/api/v1/team/members");
     return body.members;
@@ -2033,6 +2131,23 @@ class AgentComposeClient {
     const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
     return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/secrets/${encodeURIComponent(key)}`, { method: "DELETE" });
   }
+  async listSessionSecrets(conversationId) {
+    const body = await this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/secrets`);
+    return body.secrets;
+  }
+  async setSessionSecrets(conversationId, secrets) {
+    const body = await this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/secrets`, { method: "POST", body: { secrets } });
+    return body.set;
+  }
+  deleteSessionSecret(conversationId, key) {
+    return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/secrets/${encodeURIComponent(key)}`, { method: "DELETE" });
+  }
+  requestSessionSecrets(conversationId, keys, opts) {
+    return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/secret-requests`, { method: "POST", body: { keys, ...opts?.reason ? { reason: opts.reason } : {} } });
+  }
+  getSessionSecretRequest(conversationId, requestId) {
+    return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/secret-requests/${encodeURIComponent(requestId)}`);
+  }
   createApiKey(input) {
     return this.fetch("/api-keys", { method: "POST", body: input });
   }
@@ -3298,7 +3413,7 @@ Re-emit the COMPLETE corrected <response> JSON now: every required field present
           continue;
         }
         const msg = outputVerdict.value;
-        if (msg.type === "text_delta" || msg.type === "usage_delta")
+        if (msg.type === "text_delta" || msg.type === "usage_delta" || msg.type === "task_notification" || msg.type === "harness_notice")
           continue;
         opts.onAgentEvent?.(iteration, msg);
         const summary = summarizeAgentMessage(msg);
@@ -3683,6 +3798,73 @@ function createClaudeRuntime(config = {}) {
   });
 }
 var claude_default = createClaudeRuntime();
+// src/agent/perf-sampler.ts
+var PERF_SAMPLE_EVERY_BEATS = 6;
+var PERF_PROBE_WINDOW_SECONDS = 2;
+var PERF_PROBE_LINE_PREFIX = "perf ";
+var PERF_TOKEN_MAX_CHARS = 200;
+function perfReadFunctionFragment(procRoot, diskPath) {
+  const stat = shellQuote(`${procRoot}/stat`);
+  const loadavg = shellQuote(`${procRoot}/loadavg`);
+  const meminfo = shellQuote(`${procRoot}/meminfo`);
+  const disk = shellQuote(diskPath);
+  return `ac_perf_read() { ` + `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)"; ` + `}; `;
+}
+function perfSamplerFunctionFragment(paths) {
+  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; ` + `}; `;
+}
+function standalonePerfProbeCommand(opts = {}) {
+  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:--}"`;
+}
+function parsePerfToken(token) {
+  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;
+  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) => {
+    const n = Number(kv.get(k));
+    return Number.isFinite(n) && n >= 0 && n <= 100 ? Math.round(n) : null;
+  };
+  const bounded = (k, min, max) => {
+    const n = Number(kv.get(k));
+    return Number.isInteger(n) && n >= min && n <= max ? n : null;
+  };
+  const l1raw = Number(kv.get("l1"));
+  const sample = {
+    cpuBusyPct: pct("cpu"),
+    load1: Number.isFinite(l1raw) && l1raw >= 0 && l1raw <= 1e5 ? l1raw : null,
+    memUsedPct: pct("mem"),
+    diskUsedPct: pct("dsk"),
+    vcpus: bounded("vc", 1, 1024),
+    ramMb: bounded("ram", 1, 16 * 1024 * 1024),
+    sampledAtS: bounded("ts", 1577836800, 4102444800)
+  };
+  if (sample.cpuBusyPct === null && sample.load1 === null && sample.memUsedPct === null && sample.diskUsedPct === null)
+    return null;
+  return sample;
+}
+function parsePerfProbeOutput(stdout) {
+  const lines = stdout.split(`
+`).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);
+}
+
 // src/runtimes/_cli-agent.ts
 import { ndJsonStream } from "@agentclientprotocol/sdk";
 
@@ -3799,10 +3981,113 @@ function now4() {
   return new Date().toISOString();
 }
 var TAIL_REATTACH_DELAY_MS = 2000;
+var RUNNER_HEARTBEAT_INTERVAL_SECONDS = 10;
+var RUNNER_BUSY_TASK_FRESH_MINUTES = 2;
+var RUNNER_BUSY_TASK_ID_LIMIT = 16;
+function runnerBusySentinelFragment(busyPath, tasksPath) {
+  return `ac_task_files=$(find "$HOME/.claude/tasks" -type f -mmin -${RUNNER_BUSY_TASK_FRESH_MINUTES} 2>/dev/null); ` + `if [ -n "$ac_task_files" ]; then ac_busy=$(printf '%s\\n' "$ac_task_files" | wc -l | tr -cd 0-9); else ac_busy=0; fi; ` + `printf '%s' "$ac_busy" > ${shellQuote(busyPath)} 2>/dev/null; ` + `printf '%s\\n' "$ac_task_files" | sed 's|.*/tasks/||; s|/.*||' | grep . | sort -u ` + `| head -${RUNNER_BUSY_TASK_ID_LIMIT} > ${shellQuote(tasksPath)} 2>/dev/null`;
+}
+var RUNNER_HEARTBEAT_STALE_MS = RUNNER_HEARTBEAT_INTERVAL_SECONDS * 1000 * 3;
+var TAIL_WATCHDOG_INTERVAL_MS = 15000;
+var TURN_PROBE_TIMEOUT_MS = 1e4;
+var TAIL_ABANDON_AFTER_STREAM_DEATHS = 3;
+var DURABLE_POLL_INTERVAL_MS = 1000;
+var RESUME_TARGET_MISSING_STDERR = /no conversation found with session id/i;
+function turnLivenessProbeCommand(paths) {
+  return `sz=$(wc -c < ${shellQuote(paths.outPath)} 2>/dev/null || echo -1); ` + `alive=0; kill -0 ${paths.pid} 2>/dev/null && alive=1; ` + `hb=$(cat ${shellQuote(paths.hbPath)} 2>/dev/null || echo 0); ` + `now=$(date +%s%3N); ` + `sent=$(grep -c -F ${shellQuote(paths.sentinel)} ${shellQuote(paths.outPath)} 2>/dev/null || echo 0); ` + `pf=$(head -c ${PERF_TOKEN_MAX_CHARS} ${shellQuote(paths.perfPath)} 2>/dev/null | tr -cd 'A-Za-z0-9=,.-'); ` + `printf '%s %s %s %s %s %s\\n' "$sz" "$alive" "$hb" "$now" "$sent" "\${pf:--}"`;
+}
+function parseTurnProbeOutput(raw) {
+  const fields = raw.trim().split(/\s+/);
+  if (fields.length < 5)
+    return null;
+  const size = Number.parseInt(fields[0], 10);
+  const alive = fields[1] === "1" ? true : fields[1] === "0" ? false : null;
+  const hbMs = Number.parseInt(fields[2], 10);
+  const nowMs = Number.parseInt(fields[3], 10);
+  const sentinelCount = Number.parseInt(fields[4], 10);
+  if (!Number.isFinite(size) || alive === null || !Number.isFinite(hbMs) || !Number.isFinite(nowMs) || !Number.isFinite(sentinelCount))
+    return null;
+  const perfTok = fields[5];
+  const perf = perfTok !== undefined && perfTok !== "-" ? parsePerfToken(perfTok) : null;
+  return {
+    size,
+    alive,
+    hbMs,
+    nowMs,
+    sentinelSeen: sentinelCount > 0,
+    ...perf ? { perf } : {}
+  };
+}
+function livenessVerdictFromReading(reading) {
+  if (reading === null)
+    return "probe-failed";
+  if (reading.alive)
+    return "alive";
+  if (reading.sentinelSeen)
+    return "alive";
+  if (reading.hbMs > 0 && reading.nowMs - reading.hbMs <= RUNNER_HEARTBEAT_STALE_MS)
+    return "alive";
+  return "dead";
+}
+var INJECT_FEEDER_POLL_SECONDS = "0.3";
+var INJECT_FEEDER_RESULT_TAIL_BYTES = 262144;
+var INJECT_ACK_POLL_ATTEMPTS = 30;
+var INJECT_ACK_POLL_SECONDS = "0.5";
+var INJECT_ACK_EXEC_TIMEOUT_MS = 25000;
+function streamInputFeederFragment(paths) {
+  const q2 = shellQuote;
+  return `rm -f ${q2(paths.fifoPath)}; mkfifo ${q2(paths.fifoPath)}; ` + `: > ${q2(paths.inboxPath)}; echo 0 > ${q2(paths.deliveredPath)}; ` + `( cat ${q2(paths.promptPath)}; ac_fed=0; while kill -0 "$$" 2>/dev/null; do ` + `if tail -c ${INJECT_FEEDER_RESULT_TAIL_BYTES} ${q2(paths.outPath)} 2>/dev/null | grep -q '"type":"result"'; then break; fi; ` + `ac_lines=$(wc -l < ${q2(paths.inboxPath)} 2>/dev/null || echo 0); ac_lines=\${ac_lines:-0}; ` + `if [ "$ac_lines" -gt "$ac_fed" ]; then ` + `sed -n "$((ac_fed+1)),$((ac_lines))p" ${q2(paths.inboxPath)}; ac_fed=$ac_lines; ` + `echo "$ac_fed" > ${q2(paths.deliveredPath)}; fi; ` + `sleep ${INJECT_FEEDER_POLL_SECONDS}; done ) > ${q2(paths.fifoPath)} 2>/dev/null </dev/null & `;
+}
+function wrapMidTurnUserMessage(text) {
+  return `The user sent a new message while you were working:
+
+` + text + `
+
+Address the message above as you continue this turn.`;
+}
+function injectAppendAndAckCommand(args) {
+  const q2 = shellQuote;
+  return `printf '%s\\n' ${q2(args.line)} >> ${q2(args.inboxPath)}; i=0; ` + `while [ "$i" -lt ${INJECT_ACK_POLL_ATTEMPTS} ]; do ` + `d=$(cat ${q2(args.deliveredPath)} 2>/dev/null || echo 0); ` + `[ "\${d:-0}" -ge ${args.target} ] && exit 0; ` + `kill -0 ${args.pid} 2>/dev/null || exit 4; ` + `sleep ${INJECT_ACK_POLL_SECONDS}; i=$((i+1)); done; exit 5`;
+}
+var REAP_TERM_WAIT_ATTEMPTS = 20;
+var REAP_KILL_WAIT_ATTEMPTS = 8;
+var REAP_POLL_SECONDS = "0.25";
+var REAP_STILL_ALIVE_EXIT = 7;
+var REAP_EXEC_TIMEOUT_MS = 15000;
+function reapKillAndConfirmCommand(pid) {
+  const alive = `kill -0 ${pid} 2>/dev/null`;
+  return `kill -TERM -- -${pid} 2>/dev/null; kill -TERM ${pid} 2>/dev/null; ac_ri=0; ` + `while [ "$ac_ri" -lt ${REAP_TERM_WAIT_ATTEMPTS} ]; do ${alive} || exit 0; ` + `sleep ${REAP_POLL_SECONDS}; ac_ri=$((ac_ri+1)); done; ` + `kill -KILL -- -${pid} 2>/dev/null; kill -KILL ${pid} 2>/dev/null; ac_ri=0; ` + `while [ "$ac_ri" -lt ${REAP_KILL_WAIT_ATTEMPTS} ]; do ${alive} || exit 0; ` + `sleep ${REAP_POLL_SECONDS}; ac_ri=$((ac_ri+1)); done; ` + `exit ${REAP_STILL_ALIVE_EXIT}`;
+}
+var RESIDENT_IDLE_TTL_S = 240;
+var RESIDENT_WATCHDOG_POLL_S = 15;
+var RESIDENT_RESULT_LINE_PREFIX = '{"type":"result"';
+function residentResultCountCommand(outPath, fromByte = 0) {
+  const q2 = shellQuote;
+  const src = fromByte > 0 ? `tail -c +${fromByte + 1} ${q2(outPath)} 2>/dev/null` : `cat ${q2(outPath)} 2>/dev/null`;
+  return `ac_res=$(${src} | grep -c ${q2(`^${RESIDENT_RESULT_LINE_PREFIX}`)}); echo "\${ac_res:-0}"`;
+}
+function residentFeederFragment(paths) {
+  const q2 = shellQuote;
+  return `rm -f ${q2(paths.fifoPath)}; mkfifo ${q2(paths.fifoPath)}; ` + `: > ${q2(paths.inboxPath)}; echo 0 > ${q2(paths.deliveredPath)}; rm -f ${q2(paths.endPath)}; ` + `( cat ${q2(paths.promptPath)}; ac_fed=0; while kill -0 "$$" 2>/dev/null; do ` + `if [ -f ${q2(paths.endPath)} ]; then break; fi; ` + `ac_lines=$(wc -l < ${q2(paths.inboxPath)} 2>/dev/null || echo 0); ac_lines=\${ac_lines:-0}; ` + `if [ "$ac_lines" -gt "$ac_fed" ]; then ` + `sed -n "$((ac_fed+1)),$((ac_lines))p" ${q2(paths.inboxPath)}; ac_fed=$ac_lines; ` + `echo "$ac_fed" > ${q2(paths.deliveredPath)}; fi; ` + `sleep ${INJECT_FEEDER_POLL_SECONDS}; done ) > ${q2(paths.fifoPath)} 2>/dev/null </dev/null & `;
+}
+function residentIdleCheckFragment(paths) {
+  const q2 = shellQuote;
+  return `ac_res=$(grep -c ${q2(`^${RESIDENT_RESULT_LINE_PREFIX}`)} ${q2(paths.outPath)} 2>/dev/null); ac_res=\${ac_res:-0}; ` + `ac_srv=$(cat ${q2(paths.servedPath)} 2>/dev/null); ac_srv=\${ac_srv:-1}; ` + `ac_in=$(wc -l < ${q2(paths.inboxPath)} 2>/dev/null); ac_in=\${ac_in:-0}; ` + `ac_del=$(cat ${q2(paths.deliveredPath)} 2>/dev/null); ac_del=\${ac_del:-0}; ` + `if [ "$ac_res" -ge "$ac_srv" ] && [ "$ac_in" -eq "$ac_del" ]; then ac_idle=1; else ac_idle=0; fi; `;
+}
+function residentIdleWatchdogFragment(paths) {
+  return `( ac_idle_s=0; while kill -0 "$$" 2>/dev/null; do ` + residentIdleCheckFragment(paths) + `if [ "$ac_idle" = 1 ] && find "$HOME/.claude/tasks" -type f -mmin -${RUNNER_BUSY_TASK_FRESH_MINUTES} 2>/dev/null | grep -q .; then ac_idle=0; fi; ` + `if [ "$ac_idle" = 1 ]; then ac_idle_s=$((ac_idle_s+${RESIDENT_WATCHDOG_POLL_S})); else ac_idle_s=0; fi; ` + `if [ "$ac_idle_s" -ge ${RESIDENT_IDLE_TTL_S} ]; then kill -- -$$ 2>/dev/null; exit 0; fi; ` + `sleep ${RESIDENT_WATCHDOG_POLL_S}; done ) >/dev/null 2>&1 </dev/null & `;
+}
+function deferredExitEventPushCommand(notify, turnIdFile) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(notify.tokenEnv))
+    return "";
+  const q2 = shellQuote;
+  return `( ac_tid=$(cat ${q2(turnIdFile)} 2>/dev/null | tr -cd 'A-Za-z0-9-'); ` + `if [ -n "$ac_tid" ] && [ -n "$${notify.tokenEnv}" ] && command -v curl >/dev/null 2>&1; then ` + `curl -fsS -m ${EXIT_PUSH_ATTEMPT_TIMEOUT_SECONDS} -o /dev/null -X POST ` + `-H "Authorization: Bearer $${notify.tokenEnv}" ` + `-H 'Content-Type: application/json' --data "{\\"turnId\\":\\"$ac_tid\\",\\"exitCode\\":$ac_rc}" ${q2(notify.url)}; ` + `fi ) >/dev/null 2>&1 || true`;
+}
 var LAUNCH_EXEC_TIMEOUT_MS = 30000;
 var LAUNCH_PID_RECOVERY_ATTEMPTS = 3;
 var LAUNCH_PID_RECOVERY_DELAY_MS = 1000;
 var INSTALL_PROBE_TIMEOUT_MS = 30000;
+var CLI_INSTALL_TIMEOUT_MS = 300000;
 function parsePid(raw) {
   const pid = Number.parseInt(raw.trim().split(`
 `).pop() ?? "", 10);
@@ -3824,6 +4109,30 @@ async function recoverLaunchPid(read, pidPath) {
 function shellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+var SESSION_ENV_FILE_RELPATH = ".agent-compose/session-env.sh";
+var SESSION_ENV_FILE_SAFE = /^[A-Za-z0-9._\/-]+$/;
+function sessionEnvSourceFragment(relPath) {
+  if (!relPath || !SESSION_ENV_FILE_SAFE.test(relPath) || relPath.includes(".."))
+    return "";
+  return `[ -f "$HOME/${relPath}" ] && . "$HOME/${relPath}" >/dev/null 2>&1 || true; `;
+}
+function credEnvSourceFragment(absPath) {
+  if (!absPath || !absPath.startsWith("/") || !SESSION_ENV_FILE_SAFE.test(absPath.slice(1)) || absPath.includes(".."))
+    return "";
+  return `[ -f "${absPath}" ] && . "${absPath}" >/dev/null 2>&1 || true; `;
+}
+var EXIT_PUSH_ATTEMPT_TIMEOUT_SECONDS = 5;
+var EXIT_PUSH_RETRY_DELAY_SECONDS = 1;
+function exitEventPushCommand(notify) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(notify.tokenEnv))
+    return "";
+  if (!/^[A-Za-z0-9-]{1,64}$/.test(notify.turnId))
+    return "";
+  const token = `"$${notify.tokenEnv}"`;
+  const body = `"{\\"turnId\\":\\"${notify.turnId}\\",\\"exitCode\\":$ac_rc}"`;
+  const attempt = `curl -fsS -m ${EXIT_PUSH_ATTEMPT_TIMEOUT_SECONDS} -o /dev/null -X POST` + ` -H "Authorization: Bearer $${notify.tokenEnv}"` + ` -H 'Content-Type: application/json' --data ${body} ${shellQuote(notify.url)}`;
+  return `( if [ -n ${token} ] && command -v curl >/dev/null 2>&1; then ` + `${attempt} || { sleep ${EXIT_PUSH_RETRY_DELAY_SECONDS}; ${attempt}; }; ` + `fi ) >/dev/null 2>&1 || true`;
+}
 var promptFileCounter = 0;
 function uniquePromptPath(kind, agentId, iteration) {
   const unique = `${Date.now().toString(36)}-${(promptFileCounter++).toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
@@ -3863,6 +4172,60 @@ class CliAgentRunner {
   acpSession;
   currentAcpProcCtx;
   acpTransportReady = ACP_TRANSPORT_READY;
+  turnProbe = null;
+  turnInject = null;
+  async injectUserMessage(text) {
+    const inject = this.turnInject;
+    const streamInput = this.spec.streamInput;
+    if (!inject || !streamInput || this.guestDetached)
+      return "unsupported";
+    const line = streamInput.messageLine(wrapMidTurnUserMessage(text));
+    const attempt = inject.chain.then(async () => {
+      if (this.turnInject !== inject)
+        return "closed";
+      const target = inject.appended + 1;
+      inject.appended = target;
+      try {
+        const res = await this.sandbox.commands.run(injectAppendAndAckCommand({
+          line,
+          target,
+          pid: inject.pid,
+          inboxPath: inject.inboxPath,
+          deliveredPath: inject.deliveredPath
+        }), { timeoutMs: INJECT_ACK_EXEC_TIMEOUT_MS });
+        if (res.exitCode === 0)
+          return "delivered";
+        return res.exitCode === 5 ? "pending" : "closed";
+      } catch {
+        return "closed";
+      }
+    });
+    inject.chain = attempt.catch(() => {
+      return;
+    });
+    return attempt;
+  }
+  async probeTurnLiveness() {
+    const probe = this.turnProbe;
+    if (!probe)
+      return null;
+    return livenessVerdictFromReading(await probe());
+  }
+  wakeTailWatchdog = null;
+  nudgePending = false;
+  nudgeTurnProbe() {
+    const wake = this.wakeTailWatchdog;
+    if (wake) {
+      this.wakeTailWatchdog = null;
+      wake();
+    } else {
+      this.nudgePending = true;
+    }
+  }
+  guestDetached = false;
+  detachGuest() {
+    this.guestDetached = true;
+  }
   constructor(sandbox, options, spec, configModel, configEffort) {
     this.sandbox = sandbox;
     this.options = options;
@@ -3911,7 +4274,7 @@ class CliAgentRunner {
       this.installed = true;
       return;
     }
-    const res = await this.sandbox.commands.run(this.spec.install, { timeoutMs: 300000 });
+    const res = await this.sandbox.commands.run(this.spec.install, { timeoutMs: CLI_INSTALL_TIMEOUT_MS });
     if (res.exitCode !== 0) {
       throw new Error(`failed to install ${this.spec.bin}: ${(res.stderr || res.stdout || "").slice(-500)}`);
     }
@@ -4052,17 +4415,25 @@ class CliAgentRunner {
         return;
       await this.ensureInstalled();
       const promptPath = uniquePromptPath(this.spec.kind, this.options.agentId ?? "agent", opts.iteration ?? 0);
-      await this.sandbox.files.write(promptPath, this.spec.promptPayload(opts.prompt));
+      this.turnProbe = null;
+      this.turnInject = null;
+      this.nudgePending = false;
+      this.wakeTailWatchdog = null;
+      const streamInput = this.spec.streamInput !== undefined && this.sandbox.commands.runBackground !== undefined;
+      const fifoPath = `${promptPath}.fifo`;
+      const promptWrite = this.sandbox.files.write(promptPath, streamInput ? `${this.spec.streamInput.promptLine(opts.prompt)}
+` : this.spec.promptPayload(opts.prompt));
       const cmd = this.spec.buildCommand({
-        promptPath,
+        promptPath: streamInput ? fifoPath : promptPath,
         sessionId: opts.sessionId,
         model: this.model,
         cwd: this.options.cwd,
-        effort: this.configEffort
+        effort: this.configEffort,
+        ...streamInput ? { streamInput: true } : {}
       });
       const guardPath = `${promptPath}.guard.js`;
       const sentinel = `__AC_JSONL_EXIT_${Math.random().toString(36).slice(2, 10)}__`;
-      await this.sandbox.files.write(guardPath, jsonlGuardScript());
+      await Promise.all([promptWrite, this.sandbox.files.write(guardPath, jsonlGuardScript())]);
       const guardedCmd = wrapJsonlCommand({
         cmd,
         guardPath,
@@ -4076,14 +4447,23 @@ class CliAgentRunner {
       let transportError = null;
       let consumerStopped = false;
       let reap = () => {};
+      let reapConfirm = null;
       let transport;
       const durableRead = this.sandbox.files.read?.bind(this.sandbox.files);
       if (this.sandbox.commands.runBackground) {
         const outPath = `${promptPath}.out`;
         const errPath = `${promptPath}.err`;
-        const detachedScript = `{ ${guardedCmd}; } >> ${shellQuote(outPath)} 2>> ${shellQuote(errPath)} </dev/null; ` + `printf '\\n%s %s\\n' ${shellQuote(sentinel)} "$?" >> ${shellQuote(outPath)}`;
+        const hbPath = `${promptPath}.hb`;
+        const exitPush = this.options.turnExitNotify ? exitEventPushCommand(this.options.turnExitNotify) : "";
+        const busyPath = `${promptPath}.busy`;
+        const tasksPath = `${promptPath}.tasks`;
+        const inboxPath = `${promptPath}.inbox`;
+        const deliveredPath = `${promptPath}.delivered`;
+        const feeder = streamInput ? streamInputFeederFragment({ promptPath, fifoPath, inboxPath, deliveredPath, outPath }) : "";
+        const perfPath = `${promptPath}.perf`;
+        const detachedScript = feeder + `( ${perfSamplerFunctionFragment({ perfPath })}while kill -0 "$$" 2>/dev/null; do ` + `date +%s%3N > ${shellQuote(hbPath)}; ` + `${runnerBusySentinelFragment(busyPath, tasksPath)}; ` + `ac_perf_tick; ` + `sleep ${RUNNER_HEARTBEAT_INTERVAL_SECONDS}; done ) >/dev/null 2>&1 </dev/null & ` + sessionEnvSourceFragment(this.options.sessionEnvFile) + credEnvSourceFragment(this.options.credEnvFile) + `{ ${guardedCmd}; } >> ${shellQuote(outPath)} 2>> ${shellQuote(errPath)} </dev/null; ac_rc=$?; ` + `printf '\\n%s %s\\n' ${shellQuote(sentinel)} "$ac_rc" >> ${shellQuote(outPath)}` + (exitPush ? `; ${exitPush}` : "");
         const pidPath = `${promptPath}.pid`;
-        const launchCmd = `: > ${shellQuote(outPath)}; : > ${shellQuote(errPath)}; ` + `if command -v setsid >/dev/null 2>&1; then setsid sh -c ${shellQuote(detachedScript)} >/dev/null 2>&1 </dev/null & ` + `else sh -c ${shellQuote(detachedScript)} >/dev/null 2>&1 </dev/null & fi; ` + `echo "$!" > ${shellQuote(pidPath)}; echo "$!"`;
+        const launchCmd = `: > ${shellQuote(outPath)}; : > ${shellQuote(errPath)}; date +%s%3N > ${shellQuote(hbPath)}; ` + `if command -v setsid >/dev/null 2>&1; then setsid sh -c ${shellQuote(detachedScript)} >/dev/null 2>&1 </dev/null & ` + `else sh -c ${shellQuote(detachedScript)} >/dev/null 2>&1 </dev/null & fi; ` + `echo "$!" > ${shellQuote(pidPath)}; echo "$!"`;
         let pid = Number.NaN;
         let launched = null;
         let launchErr = null;
@@ -4106,6 +4486,19 @@ class CliAgentRunner {
             throw launchErr;
           console.warn(`[cli-agent] ${this.spec.kind} launch exec stream died but the detached runner is up ` + `(pid ${pid} via ${pidPath}) — continuing on the durable transport: ${formatError(launchErr)}`);
         }
+        const probeCmd = turnLivenessProbeCommand({ outPath, hbPath, perfPath, pid, sentinel });
+        const runTurnProbe = async () => {
+          try {
+            const res = await this.sandbox.commands.run(probeCmd, { timeoutMs: TURN_PROBE_TIMEOUT_MS });
+            return parseTurnProbeOutput(res.stdout ?? "");
+          } catch {
+            return null;
+          }
+        };
+        this.turnProbe = runTurnProbe;
+        if (streamInput) {
+          this.turnInject = { inboxPath, deliveredPath, pid, appended: 0, chain: Promise.resolve() };
+        }
         let offset = 0;
         let currentTail = null;
         const consumeLine = (raw) => {
@@ -4121,10 +4514,15 @@ class CliAgentRunner {
           lines.push(line);
         };
         reap = () => {
-          this.sandbox.commands.run(`kill -TERM -- -${pid} 2>/dev/null; kill -TERM ${pid} 2>/dev/null; true`, { timeoutMs: 1e4 }).catch(() => {});
+          reapConfirm ??= this.sandbox.commands.run(reapKillAndConfirmCommand(pid), { timeoutMs: REAP_EXEC_TIMEOUT_MS }).then((res) => {
+            if (res.exitCode === REAP_STILL_ALIVE_EXIT) {
+              console.warn(`[cli-agent] ${this.spec.kind} runner ${pid} survived SIGKILL's confirm window ` + "— the next launch's preflight is the backstop");
+            }
+          }).catch(() => {});
           currentTail?.kill().catch(() => {});
         };
         transport = (async () => {
+          let streamDeaths = 0;
           while (exitCode === null && !consumerStopped && !opts.signal?.aborted) {
             let buf = "";
             let handle = null;
@@ -4141,16 +4539,68 @@ class CliAgentRunner {
                 }
               }
             };
-            try {
-              handle = await this.sandbox.commands.runBackground(`tail -c +${offset + 1} -f ${shellQuote(outPath)}`, { timeoutMs: 0, onStdout });
-            } catch {}
+            if (streamDeaths < TAIL_ABANDON_AFTER_STREAM_DEATHS) {
+              try {
+                handle = await this.sandbox.commands.runBackground(`tail -s 0.05 -c +${offset + 1} -f ${shellQuote(outPath)}`, { timeoutMs: 0, onStdout });
+              } catch {}
+            }
             if (handle) {
               if (exitCode !== null)
                 handle.kill().catch(() => {});
               currentTail = handle;
-              await handle.wait().catch(() => {
-                return;
-              });
+              await (async (tail) => {
+                let waitSettled = false;
+                const waitP = tail.wait().catch(() => {
+                  return;
+                }).then(() => {
+                  waitSettled = true;
+                });
+                let lastTickOffset = -1;
+                while (!waitSettled) {
+                  let onAbort;
+                  const wake = new Promise((resolve) => {
+                    const t = setTimeout(resolve, TAIL_WATCHDOG_INTERVAL_MS);
+                    t.unref?.();
+                    const fire = () => {
+                      clearTimeout(t);
+                      resolve();
+                    };
+                    if (this.nudgePending) {
+                      this.nudgePending = false;
+                      fire();
+                    } else {
+                      this.wakeTailWatchdog = fire;
+                    }
+                    if (opts.signal) {
+                      onAbort = fire;
+                      opts.signal.addEventListener("abort", onAbort, { once: true });
+                    }
+                  });
+                  await Promise.race([waitP, wake]);
+                  this.wakeTailWatchdog = null;
+                  if (onAbort)
+                    opts.signal?.removeEventListener("abort", onAbort);
+                  if (waitSettled || exitCode !== null || consumerStopped || opts.signal?.aborted)
+                    return;
+                  const tickOffset = offset;
+                  const reading = await runTurnProbe();
+                  if (offset !== tickOffset) {
+                    lastTickOffset = offset;
+                    continue;
+                  }
+                  if (reading === null) {
+                    lastTickOffset = tickOffset;
+                    continue;
+                  }
+                  const streamStarved = reading.size > offset && tickOffset === lastTickOffset;
+                  if (reading.sentinelSeen || !reading.alive || streamStarved) {
+                    console.warn(`[cli-agent] ${this.spec.kind} tail stream ${reading.sentinelSeen ? "outlived the FINISHED turn (durable sentinel unharvested)" : !reading.alive ? "outlived the runner" : `starved (durable file at ${reading.size} bytes, stream stuck at ${offset})`}` + " — killing the tail and catching up from the durable file");
+                    tail.kill().catch(() => {});
+                    return;
+                  }
+                  lastTickOffset = tickOffset;
+                }
+              })(handle);
               currentTail = null;
             }
             if (exitCode !== null || consumerStopped || opts.signal?.aborted)
@@ -4180,8 +4630,16 @@ class CliAgentRunner {
               exitCode = JSONL_GUARD_NO_SENTINEL_EXIT;
               break;
             }
-            console.warn(`[cli-agent] ${this.spec.kind} turn stream lost with the runner alive — re-tailing ${outPath} from byte ${offset}`);
-            await new Promise((r) => setTimeout(r, TAIL_REATTACH_DELAY_MS));
+            streamDeaths += 1;
+            if (streamDeaths < TAIL_ABANDON_AFTER_STREAM_DEATHS) {
+              console.warn(`[cli-agent] ${this.spec.kind} turn stream lost with the runner alive — re-tailing ${outPath} from byte ${offset}`);
+              await new Promise((r) => setTimeout(r, TAIL_REATTACH_DELAY_MS));
+            } else {
+              if (streamDeaths === TAIL_ABANDON_AFTER_STREAM_DEATHS) {
+                console.warn(`[cli-agent] ${this.spec.kind} turn abandoning streaming after ` + `${streamDeaths} stream deaths — finishing on durable polling from byte ${offset}`);
+              }
+              await new Promise((r) => setTimeout(r, DURABLE_POLL_INTERVAL_MS));
+            }
           }
           if (exitCode !== null && exitCode !== 0 && durableRead) {
             try {
@@ -4207,7 +4665,7 @@ class CliAgentRunner {
           onStdout,
           timeoutMs: 0
         };
-        transport = this.sandbox.commands.run(guardedCmd, runOpts).then((res) => {
+        transport = this.sandbox.commands.run(credEnvSourceFragment(this.options.credEnvFile) + guardedCmd, runOpts).then((res) => {
           const tail = buf.trim();
           if (tail)
             lines.push(tail);
@@ -4218,13 +4676,18 @@ class CliAgentRunner {
         }).finally(() => lines.close());
       }
       transport.catch(() => {});
+      const reapUnlessDetached = () => {
+        if (!this.guestDetached)
+          reap();
+      };
       if (opts.signal) {
         if (opts.signal.aborted)
-          reap();
+          reapUnlessDetached();
         else
-          opts.signal.addEventListener("abort", reap, { once: true });
+          opts.signal.addEventListener("abort", reapUnlessDetached, { once: true });
       }
       try {
+        let announcedSessionId = opts.sessionId ?? "";
         for await (const line of lines) {
           let parsed;
           try {
@@ -4235,6 +4698,10 @@ class CliAgentRunner {
           const sid = this.spec.extractSessionId(parsed);
           if (sid)
             sessionId = sid;
+          if (sid && sid !== announcedSessionId) {
+            announcedSessionId = sid;
+            yield { type: "init", sessionId: sid, timestamp: now4() };
+          }
           for (const msg of this.spec.mapEvent(parsed)) {
             if (msg.type === "error")
               sawError = true;
@@ -4255,14 +4722,23 @@ class CliAgentRunner {
           yield { type: "error", text: `${this.spec.kind} exited with code ${exitCode}${detail}${exitStderr ? `: ${exitStderr}` : ""}`, timestamp: now4() };
           return;
         }
+        if (exitCode !== 0 && sawError && RESUME_TARGET_MISSING_STDERR.test(exitStderr)) {
+          yield { type: "error", text: `${this.spec.kind} exited with code ${exitCode}: ${exitStderr}`, timestamp: now4() };
+          return;
+        }
         if (!sawError)
           yield { type: "done", sessionId: sessionId ?? "", timestamp: now4() };
       } finally {
-        opts.signal?.removeEventListener("abort", reap);
+        opts.signal?.removeEventListener("abort", reapUnlessDetached);
         consumerStopped = true;
-        if (exitCode === null)
+        if (exitCode === null && !this.guestDetached)
           reap();
-        this.sandbox.commands.run(`rm -f ${shellQuote(promptPath)} ${shellQuote(guardPath)} ${shellQuote(`${promptPath}.out`)} ${shellQuote(`${promptPath}.err`)} ${shellQuote(`${promptPath}.pid`)}`, { timeoutMs: 1e4 }).catch(() => {});
+        if (reapConfirm)
+          await reapConfirm;
+        this.turnInject = null;
+        if (!this.guestDetached) {
+          this.sandbox.commands.run(`rm -f ${shellQuote(promptPath)} ${shellQuote(guardPath)} ${shellQuote(`${promptPath}.out`)} ${shellQuote(`${promptPath}.err`)} ${shellQuote(`${promptPath}.pid`)} ${shellQuote(`${promptPath}.hb`)} ${shellQuote(`${promptPath}.busy`)} ${shellQuote(`${promptPath}.tasks`)} ${shellQuote(`${promptPath}.fifo`)} ${shellQuote(`${promptPath}.inbox`)} ${shellQuote(`${promptPath}.delivered`)}`, { timeoutMs: 1e4 }).catch(() => {});
+        }
       }
     } catch (err) {
       yield { type: "error", text: formatError(err), timestamp: now4() };
@@ -4286,10 +4762,19 @@ var CODEX_ADVISORY_PATTERNS = [
 function isCodexAdvisoryNoise(text) {
   return CODEX_ADVISORY_PATTERNS.some((re) => re.test(text));
 }
+var CODEX_LOCK_WAIT_ATTEMPTS = 20;
+var CODEX_LOCK_WAIT_SECONDS = "0.25";
+var CODEX_THREAD_ID_SAFE = /^[A-Za-z0-9_-]{1,64}$/;
+function codexWriterLockPreflight(threadId, waitAttempts = CODEX_LOCK_WAIT_ATTEMPTS) {
+  if (!CODEX_THREAD_ID_SAFE.test(threadId))
+    return "";
+  return `ac_lk="\${CODEX_HOME:-$HOME/.codex}/thread-writer-locks/${threadId}.lock"; ` + `if [ -e "$ac_lk" ] && command -v flock >/dev/null 2>&1; then ac_lki=0; ` + `while ! flock -n "$ac_lk" true 2>/dev/null && [ "$ac_lki" -lt ${waitAttempts} ]; do ` + `sleep ${CODEX_LOCK_WAIT_SECONDS}; ac_lki=$((ac_lki+1)); done; ` + `flock -n "$ac_lk" rm -f -- "$ac_lk" 2>/dev/null || true; fi; `;
+}
 var codexSpec = {
   kind: "codex",
   authEnv: "CODEX_API_KEY",
   bin: "codex",
+  exclusiveSessionWriter: true,
   acp: {
     command: "npx",
     args: ["-y", CODEX_ACP_ADAPTER],
@@ -4306,8 +4791,9 @@ var codexSpec = {
       ...effort ? ["-c", `model_reasoning_effort=${effort === "max" ? "xhigh" : effort}`] : []
     ].join(" ");
     const cd = cwd ? `cd ${shellQuote(cwd)} && ` : "";
+    const preflight = sessionId ? codexWriterLockPreflight(sessionId) : "";
     const exec = sessionId ? `codex exec resume ${shellQuote(sessionId)} ${flags}` : `codex exec ${flags}`;
-    return `${cd}${exec} - < ${shellQuote(promptPath)}`;
+    return `${preflight}${cd}${exec} - < ${shellQuote(promptPath)}`;
   },
   extractSessionId: (p) => p.type === "thread.started" && typeof p.thread_id === "string" ? p.thread_id : undefined,
   mapEvent: (p) => {
@@ -4525,6 +5011,84 @@ function toolResultText(content) {
   }
   return content == null ? "" : JSON.stringify(content) ?? "";
 }
+var TASK_NOTIFICATION_RE = /<task-notification>([\s\S]*?)<\/task-notification>/g;
+var NOTIFICATION_SUMMARY_MAX = 500;
+var NOTIFICATION_REPORT_MAX = 20000;
+function innerTag(body, tag) {
+  const m = new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`).exec(body);
+  const text = m?.[1]?.trim() ?? "";
+  return text.length > 0 ? text : null;
+}
+function unescapeEntities(s) {
+  return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, "&");
+}
+var clip = (s, max) => s.length > max ? `${s.slice(0, max - 1)}…` : s;
+function intTag(body, tag) {
+  const raw = innerTag(body, tag);
+  if (!raw)
+    return;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+function parseTaskNotifications(text, timestamp) {
+  if (!text.includes("<task-notification>"))
+    return [];
+  const out = [];
+  TASK_NOTIFICATION_RE.lastIndex = 0;
+  for (let m = TASK_NOTIFICATION_RE.exec(text);m !== null; m = TASK_NOTIFICATION_RE.exec(text)) {
+    const body = m[1] ?? "";
+    const taskId = innerTag(body, "task-id");
+    if (!taskId)
+      continue;
+    const toolUseId = innerTag(body, "tool-use-id");
+    const summary = innerTag(body, "summary");
+    const report = innerTag(body, "result");
+    const usageBody = /<usage>([\s\S]*?)<\/usage>/.exec(body)?.[1] ?? "";
+    const tokens = intTag(usageBody, "subagent_tokens");
+    const toolUses = intTag(usageBody, "tool_uses");
+    const durationMs = intTag(usageBody, "duration_ms");
+    out.push({
+      type: "task_notification",
+      taskId: clip(taskId, 128),
+      ...toolUseId ? { toolUseId: clip(toolUseId, 128) } : {},
+      status: innerTag(body, "status") ?? "finished",
+      summary: summary ? clip(unescapeEntities(summary.replace(/\s+/g, " ")), NOTIFICATION_SUMMARY_MAX) : "",
+      ...report ? { report: clip(unescapeEntities(report), NOTIFICATION_REPORT_MAX) } : {},
+      ...tokens !== undefined || toolUses !== undefined || durationMs !== undefined ? { usage: {
+        ...tokens !== undefined ? { tokens } : {},
+        ...toolUses !== undefined ? { toolUses } : {},
+        ...durationMs !== undefined ? { durationMs } : {}
+      } } : {},
+      timestamp
+    });
+  }
+  return out;
+}
+function parseSystemTaskNotification(p, timestamp) {
+  const taskId = typeof p.task_id === "string" && p.task_id.trim().length > 0 ? p.task_id.trim() : null;
+  if (!taskId)
+    return null;
+  const toolUseId = typeof p.tool_use_id === "string" && p.tool_use_id.length > 0 ? p.tool_use_id : null;
+  const summary = typeof p.summary === "string" ? p.summary : "";
+  const nonneg = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : undefined;
+  const u = typeof p.usage === "object" && p.usage !== null ? p.usage : {};
+  const tokens = nonneg(u.total_tokens);
+  const toolUses = nonneg(u.tool_uses);
+  const durationMs = nonneg(u.duration_ms);
+  return {
+    type: "task_notification",
+    taskId: clip(taskId, 128),
+    ...toolUseId ? { toolUseId: clip(toolUseId, 128) } : {},
+    status: typeof p.status === "string" && p.status.length > 0 ? p.status : "finished",
+    summary: clip(summary.replace(/\s+/g, " ").trim(), NOTIFICATION_SUMMARY_MAX),
+    ...tokens !== undefined || toolUses !== undefined || durationMs !== undefined ? { usage: {
+      ...tokens !== undefined ? { tokens } : {},
+      ...toolUses !== undefined ? { toolUses } : {},
+      ...durationMs !== undefined ? { durationMs } : {}
+    } } : {},
+    timestamp
+  };
+}
 var CLAUDE_CODE_EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
 var claudeCodeSpec = {
   kind: "claude-code",
@@ -4533,11 +5097,16 @@ var claudeCodeSpec = {
   acp: { command: "npx", args: ["--yes", CLAUDE_CODE_ACP_ADAPTER] },
   install: "curl -fsSL https://claude.ai/install.sh | bash && " + 'REAL=$(readlink -f "$HOME/.local/bin/claude") && test -f "$REAL" && ' + 'sudo cp "$REAL" /usr/local/bin/claude && sudo chmod 0755 /usr/local/bin/claude',
   promptPayload: (prompt) => prompt,
-  buildCommand: ({ promptPath, sessionId, model, cwd, effort }) => {
+  streamInput: {
+    promptLine: (prompt) => JSON.stringify({ type: "user", message: { role: "user", content: prompt } }),
+    messageLine: (text) => JSON.stringify({ type: "user", message: { role: "user", content: text } })
+  },
+  buildCommand: ({ promptPath, sessionId, model, cwd, effort, streamInput }) => {
     const flags = [
       "-p",
       "--output-format stream-json",
       "--verbose",
+      ...streamInput ? ["--input-format stream-json"] : [],
       "--include-partial-messages",
       "--dangerously-skip-permissions",
       ...model ? [`--model ${shellQuote(model)}`] : [],
@@ -4553,10 +5122,11 @@ var claudeCodeSpec = {
     switch (p.type) {
       case "assistant": {
         const message = p.message;
+        const synthetic = message?.model === "<synthetic>";
         const blocks2 = Array.isArray(message?.content) ? message.content : [];
         return blocks2.flatMap((b) => {
           if (b.type === "text" && typeof b.text === "string" && b.text.length > 0) {
-            return [{ type: "text", text: b.text, timestamp: ts }];
+            return [{ type: synthetic ? "harness_notice" : "text", text: b.text, timestamp: ts }];
           }
           if (b.type === "thinking" && typeof b.thinking === "string" && b.thinking.length > 0) {
             return [{ type: "thinking", text: b.thinking, timestamp: ts }];
@@ -4576,15 +5146,26 @@ var claudeCodeSpec = {
       }
       case "user": {
         const message = p.message;
+        if (typeof message?.content === "string") {
+          return parseTaskNotifications(message.content, ts);
+        }
         const blocks2 = Array.isArray(message?.content) ? message.content : [];
-        return blocks2.flatMap((b) => b.type === "tool_result" ? [{
-          type: "tool_result",
-          toolUseId: String(b.tool_use_id ?? ""),
-          output: toolResultText(b.content),
-          isError: b.is_error === true,
-          ...parent,
-          timestamp: ts
-        }] : []);
+        return blocks2.flatMap((b) => {
+          if (b.type === "tool_result") {
+            return [{
+              type: "tool_result",
+              toolUseId: String(b.tool_use_id ?? ""),
+              output: toolResultText(b.content),
+              isError: b.is_error === true,
+              ...parent,
+              timestamp: ts
+            }];
+          }
+          if (b.type === "text" && typeof b.text === "string") {
+            return parseTaskNotifications(b.text, ts);
+          }
+          return [];
+        });
       }
       case "stream_event": {
         const ev = p.event;
@@ -4634,6 +5215,12 @@ var claudeCodeSpec = {
           timestamp: ts
         }];
       }
+      case "system": {
+        if (p.subtype !== "task_notification")
+          return [];
+        const notification = parseSystemTaskNotification(p, ts);
+        return notification ? [notification] : [];
+      }
       default:
         return [];
     }
@@ -4855,6 +5442,7 @@ function makeSandboxProvider(sb) {
 function e2bMaxSandboxMs() {
   return Number(process.env.E2B_MAX_SANDBOX_MS) || 60 * 60 * 1000;
 }
+var e2bExtendClampWarned = false;
 function wrapE2bBackgroundProcess(handle) {
   return {
     pid: handle.pid,
@@ -4948,7 +5536,12 @@ function makeE2bSandboxProvider(sb) {
       return { resumeHandle: sb.sandboxId };
     },
     async extendLifetime(ms) {
-      await sb.setTimeout(Math.min(ms, e2bMaxSandboxMs()));
+      const maxMs = e2bMaxSandboxMs();
+      if (ms > maxMs && !e2bExtendClampWarned) {
+        e2bExtendClampWarned = true;
+        console.warn(`[sandbox] e2b lifetime extension clamped: requested ${ms}ms exceeds the plan cap ${maxMs}ms — ` + `the kill-clock backstop fires at the cap, not the requested horizon. Raise E2B_MAX_SANDBOX_MS on plans that allow more.`);
+      }
+      await sb.setTimeout(Math.min(ms, maxMs));
     },
     async updateNetworkPolicy(policy) {
       await sb.updateNetwork(toE2bNetwork(policy));
@@ -4980,6 +5573,7 @@ var e2bProviderDef = {
     const sandboxOpts = {
       ...rest,
       timeoutMs: Math.min(timeoutMs, maxMs),
+      lifecycle: { onTimeout: "pause", autoResume: true },
       ...networkPolicy ? { network: toE2bNetwork(networkPolicy) } : {}
     };
     const resolvedSize = size ?? DEFAULT_SANDBOX_SIZE;
@@ -5252,8 +5846,9 @@ function makeLocalSandboxProvider() {
             stderr += chunk;
             opts?.onStderr?.(chunk);
           });
-          proc.on("error", reject);
-          proc.on("close", (code) => resolve({ exitCode: code ?? 0, stdout, stderr }));
+          const ev = proc;
+          ev.on("error", reject);
+          ev.on("close", (code) => resolve({ exitCode: code ?? 0, stdout, stderr }));
         });
       },
       spawnDuplex(cmd, opts) {
@@ -5269,8 +5864,9 @@ function makeLocalSandboxProvider() {
           stderr += chunk;
         });
         const exited = new Promise((resolve, reject) => {
-          proc.on("error", reject);
-          proc.on("close", (code) => resolve({ exitCode: code ?? 0, stderr }));
+          const ev = proc;
+          ev.on("error", reject);
+          ev.on("close", (code) => resolve({ exitCode: code ?? 0, stderr }));
         });
         return {
           stdin: Writable.toWeb(proc.stdin),
@@ -6574,27 +7170,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
@@ -6685,14 +7335,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.)`;
 function buildAddedSessionBrief(p) {
   const dashboardSection = p.dashboardUrl === null ? "" : `
 
@@ -6999,6 +7684,565 @@ async function agent(opts) {
     inboxAbort.abort();
   }
 }
+// src/agent/desktop-open.ts
+var AC_OPEN_PATH = "/usr/local/bin/ac-open";
+var AC_OPEN_STATE_DIR = "/tmp/.ac-desktop-open";
+var AC_OPEN_SHIM_PATHS = [
+  "/usr/local/bin/xdg-open",
+  "/usr/local/bin/sensible-browser"
+];
+var BROWSER_BACKFILL_PIDFILE = `${AC_OPEN_STATE_DIR}/browser-install.pid`;
+var BROWSER_BACKFILL_LOG = `${AC_OPEN_STATE_DIR}/browser-install.log`;
+var BROWSER_BACKFILL_FAILED = `${AC_OPEN_STATE_DIR}/browser-install.failed`;
+var 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";
+var 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
+`;
+var AC_OPEN_SHIM = `#!/bin/sh
+# agent-compose: generic open routes through ac-open (the detaching launcher).
+exec ${AC_OPEN_PATH} "$@"
+`;
+function installDesktopOpenCmd() {
+  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(" && ");
+}
+var CHROMIUM_DEFAULTS_PATH = "/etc/chromium.d/00-ac-defaults";
+var 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
+`;
+function installChromiumDefaultsCmd() {
+  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(" && ");
+}
+function browserBackfillCmd() {
+  const pid = BROWSER_BACKFILL_PIDFILE;
+  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`;
+}
+function browserBackfillStatusCmd() {
+  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`;
+}
+// src/agent/services-manifest.ts
+var SERVICES_MANIFEST_RELPATH = ".ac/services.yml";
+var SERVICES_MAX = 16;
+var SERVICE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,31}$/;
+var TOP_KEYS = new Set(["version", "services"]);
+var ENTRY_KEYS = new Set(["name", "command", "cwd", "port", "env", "setup", "health", "data"]);
+var HEALTH_KEYS = new Set(["cmd", "http"]);
+var DATA_KEYS = new Set(["dump", "restore"]);
+function lex(text) {
+  const out = [];
+  const raw = text.split(/\r?\n/);
+  for (let i = 0;i < raw.length; i++) {
+    const line = raw[i];
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#"))
+      continue;
+    const indent = line.length - line.trimStart().length;
+    const dash = trimmed.startsWith("- ") || trimmed === "-";
+    out.push({
+      no: i + 1,
+      indent,
+      dash,
+      text: dash ? trimmed.slice(1).trim() : trimmed
+    });
+  }
+  return out;
+}
+function splitKey(text) {
+  if (text.endsWith(":") && !text.includes(": ")) {
+    const key2 = text.slice(0, -1).trim();
+    return /^[A-Za-z_][\w-]*$/.test(key2) ? { key: key2, value: "" } : null;
+  }
+  const idx = text.indexOf(": ");
+  if (idx === -1)
+    return null;
+  const key = text.slice(0, idx).trim();
+  if (!/^[A-Za-z_][\w-]*$/.test(key))
+    return null;
+  return { key, value: text.slice(idx + 2).trim() };
+}
+function scalar(value, no, errors) {
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1).replace(/\\(["\\])/g, "$1");
+  }
+  if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1).replace(/''/g, "'");
+  }
+  if (value === "|" || value === ">" || value.startsWith("| ") || value.startsWith("> ")) {
+    errors.push(`line ${no}: block scalars (| / >) are not supported — keep commands single-line`);
+    return "";
+  }
+  return value;
+}
+function parseServicesManifest(text) {
+  const errors = [];
+  if (text.length > 64 * 1024) {
+    return { manifest: null, errors: ["manifest exceeds 64KB — this file is a service list, not a data store"] };
+  }
+  const lines = lex(text);
+  if (lines.length === 0)
+    return { manifest: null, errors: ["manifest is empty"] };
+  let version = null;
+  const services = [];
+  let current = null;
+  let currentIndent = -1;
+  let nested = null;
+  let nestedIndent = -1;
+  let inServices = false;
+  const finish = (entry) => {
+    if (!entry)
+      return;
+    services.push(entry);
+  };
+  for (const line of lines) {
+    const kv = splitKey(line.text);
+    if (!kv) {
+      errors.push(`line ${line.no}: not a \`key: value\` mapping — flow collections and bare scalars are not supported`);
+      continue;
+    }
+    if (line.indent === 0 && !line.dash) {
+      inServices = false;
+      nested = null;
+      finish(current);
+      current = null;
+      if (!TOP_KEYS.has(kv.key)) {
+        errors.push(`line ${line.no}: unknown top-level key \`${kv.key}\` (allowed: version, services)`);
+        continue;
+      }
+      if (kv.key === "version") {
+        const v = Number(scalar(kv.value, line.no, errors));
+        if (v !== 1)
+          errors.push(`line ${line.no}: unsupported manifest version \`${kv.value}\` (this build understands version 1)`);
+        else
+          version = 1;
+      } else {
+        if (kv.value !== "")
+          errors.push(`line ${line.no}: \`services:\` must open a list, not carry a value`);
+        inServices = true;
+      }
+      continue;
+    }
+    if (!inServices) {
+      errors.push(`line ${line.no}: unexpected indented line outside \`services:\``);
+      continue;
+    }
+    if (line.dash) {
+      finish(current);
+      current = { name: "", command: "" };
+      currentIndent = line.indent;
+      nested = null;
+      if (kv.key !== "name") {
+        errors.push(`line ${line.no}: each service entry must start with \`- name: <name>\``);
+        continue;
+      }
+      current.name = scalar(kv.value, line.no, errors);
+      continue;
+    }
+    if (!current) {
+      errors.push(`line ${line.no}: expected \`- name: <name>\` to open a service entry`);
+      continue;
+    }
+    if (nested && line.indent > nestedIndent) {
+      const allowed = nested === "health" ? HEALTH_KEYS : DATA_KEYS;
+      if (!allowed.has(kv.key)) {
+        errors.push(`line ${line.no}: unknown \`${nested}\` key \`${kv.key}\` (allowed: ${[...allowed].join(", ")})`);
+        continue;
+      }
+      const value2 = scalar(kv.value, line.no, errors);
+      if (value2 === "") {
+        errors.push(`line ${line.no}: \`${nested}.${kv.key}\` needs a value`);
+        continue;
+      }
+      const bucket = current[nested] ??= {};
+      bucket[kv.key] = value2;
+      continue;
+    }
+    nested = null;
+    if (line.indent <= currentIndent) {
+      errors.push(`line ${line.no}: bad indentation — service fields must be indented under their \`- name:\` line`);
+      continue;
+    }
+    if (!ENTRY_KEYS.has(kv.key)) {
+      errors.push(`line ${line.no}: unknown service key \`${kv.key}\` (allowed: ${[...ENTRY_KEYS].join(", ")})`);
+      continue;
+    }
+    if (kv.key === "health" || kv.key === "data") {
+      if (kv.value !== "") {
+        errors.push(`line ${line.no}: \`${kv.key}:\` opens a nested map — put cmd/http (or dump/restore) on indented lines below`);
+        continue;
+      }
+      nested = kv.key;
+      nestedIndent = line.indent;
+      continue;
+    }
+    const value = scalar(kv.value, line.no, errors);
+    if (kv.key === "port") {
+      const port = Number(value);
+      if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        errors.push(`line ${line.no}: port must be an integer 1-65535, got \`${kv.value}\``);
+      } else {
+        current.port = port;
+      }
+      continue;
+    }
+    if (value === "") {
+      errors.push(`line ${line.no}: \`${kv.key}\` needs a value`);
+      continue;
+    }
+    if (kv.key === "cwd" && (value.startsWith("/") || value.includes(".."))) {
+      errors.push(`line ${line.no}: cwd must be a relative path under the drive root (no leading / and no ..)`);
+      continue;
+    }
+    current[kv.key] = value;
+  }
+  finish(current);
+  if (version === null)
+    errors.push("missing `version: 1`");
+  if (services.length === 0 && errors.length === 0)
+    errors.push("`services:` lists no entries");
+  if (services.length > SERVICES_MAX)
+    errors.push(`too many services (${services.length}) — the cap is ${SERVICES_MAX}`);
+  const seen = new Set;
+  for (const svc of services) {
+    const label = svc.name || "<unnamed>";
+    if (!SERVICE_NAME_RE.test(svc.name)) {
+      errors.push(`service \`${label}\`: name must match ${SERVICE_NAME_RE} (alphanumeric start, then [A-Za-z0-9._-], max 32)`);
+    } else if (seen.has(svc.name)) {
+      errors.push(`service \`${label}\`: duplicate name`);
+    }
+    seen.add(svc.name);
+    if (!svc.command)
+      errors.push(`service \`${label}\`: missing \`command\``);
+    if (svc.health?.cmd && svc.health.http) {
+      errors.push(`service \`${label}\`: health takes \`cmd\` OR \`http\`, not both`);
+    }
+    if (svc.health?.http && !/^https?:\/\//.test(svc.health.http)) {
+      errors.push(`service \`${label}\`: health.http must be an http(s):// URL`);
+    }
+  }
+  return errors.length > 0 ? { manifest: null, errors } : { manifest: { version: 1, services }, errors: [] };
+}
+function emitScalar(value) {
+  const needsQuote = value !== value.trim() || value.startsWith("'") || value.startsWith('"') || value === "|" || value === ">" || value.startsWith("| ") || value.startsWith("> ");
+  if (!needsQuote)
+    return value;
+  return `"${value.replace(/([\\"])/g, "\\$1")}"`;
+}
+function renderServicesManifest(manifest) {
+  const out = [
+    "# Durable services manifest — restored automatically after a machine recycle.",
+    "# Docs: agentc services --help",
+    "version: 1",
+    "services:"
+  ];
+  for (const svc of manifest.services) {
+    out.push(`  - name: ${emitScalar(svc.name)}`);
+    out.push(`    command: ${emitScalar(svc.command)}`);
+    if (svc.cwd)
+      out.push(`    cwd: ${emitScalar(svc.cwd)}`);
+    if (svc.port !== undefined)
+      out.push(`    port: ${svc.port}`);
+    if (svc.env)
+      out.push(`    env: ${emitScalar(svc.env)}`);
+    if (svc.setup)
+      out.push(`    setup: ${emitScalar(svc.setup)}`);
+    if (svc.health && (svc.health.cmd || svc.health.http)) {
+      out.push("    health:");
+      if (svc.health.cmd)
+        out.push(`      cmd: ${emitScalar(svc.health.cmd)}`);
+      if (svc.health.http)
+        out.push(`      http: ${emitScalar(svc.health.http)}`);
+    }
+    if (svc.data && (svc.data.dump || svc.data.restore)) {
+      out.push("    data:");
+      if (svc.data.dump)
+        out.push(`      dump: ${emitScalar(svc.data.dump)}`);
+      if (svc.data.restore)
+        out.push(`      restore: ${emitScalar(svc.data.restore)}`);
+    }
+  }
+  return out.join(`
+`) + `
+`;
+}
+// src/agent/services-restore.ts
+var SERVICES_STATE_DIR = "/tmp/ac-services";
+var SERVICE_STATUS_PREFIX = "##ac-service";
+var SERVICE_HEALTH_TIMEOUT_S = 45;
+function shq(s) {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function shc(cmd) {
+  return `sh -c ${shq(cmd)}`;
+}
+function serviceCwd(driveRoot, svc) {
+  return svc.cwd ? `${driveRoot.replace(/\/+$/, "")}/${svc.cwd}` : driveRoot;
+}
+function restoreOneService(driveRoot, svc) {
+  const n = svc.name;
+  const cwd = serviceCwd(driveRoot, svc);
+  const lines = [
+    ``,
+    `# --- ${n} ---`,
+    `(`,
+    `  cd ${shq(cwd)} || { status ${shq(n)} failed cwd-missing; exit 0; }`
+  ];
+  if (svc.setup) {
+    lines.push(`  if ! ${shc(svc.setup)} >> "$D/${n}.setup.log" 2>&1; then`, `    status ${shq(n)} failed setup; exit 0`, `  fi`);
+  }
+  if (svc.data?.restore) {
+    lines.push(`  if ! ${shc(svc.data.restore)} >> "$D/${n}.setup.log" 2>&1; then`, `    status ${shq(n)} failed data-restore; exit 0`, `  fi`);
+  }
+  lines.push(`  $SETSID ${shc(svc.command)} >> "$D/${n}.log" 2>&1 < /dev/null &`, `  echo $! > "$D/${n}.pid"`);
+  const health = svc.health?.cmd ? shc(svc.health.cmd) : svc.health?.http ? `curl -fsS -m 2 -o /dev/null ${shq(svc.health.http)}` : null;
+  if (health) {
+    lines.push(`  i=0`, `  while [ "$i" -lt ${SERVICE_HEALTH_TIMEOUT_S} ]; do`, `    if ${health} >/dev/null 2>&1; then status ${shq(n)} ok ''; exit 0; fi`, `    kill -0 "$(cat "$D/${n}.pid")" 2>/dev/null || { status ${shq(n)} failed exited; exit 0; }`, `    i=$((i+1)); sleep 1`, `  done`, `  status ${shq(n)} failed health-timeout`);
+  } else {
+    lines.push(`  sleep 1`, `  if kill -0 "$(cat "$D/${n}.pid")" 2>/dev/null; then status ${shq(n)} unchecked ''; else status ${shq(n)} failed exited; fi`);
+  }
+  lines.push(`)`);
+  return lines;
+}
+function servicesRestoreScript(manifest, driveRoot) {
+  const head = [
+    `#!/bin/sh`,
+    `# generated by agent-compose — restores services from ${driveRoot}/.ac/services.yml`,
+    `# logs + pidfiles: ${SERVICES_STATE_DIR}/<name>.{log,pid}`,
+    `D=${shq(SERVICES_STATE_DIR)}`,
+    `mkdir -p "$D"`,
+    `status() { printf '%s %s %s %s\\n' ${shq(SERVICE_STATUS_PREFIX)} "$1" "$2" "$3"; }`,
+    `# setsid detaches from the boot shell's session (Linux guests); on hosts`,
+    `# without it (macOS running \`agentc services restore\`) plain & still works.`,
+    `SETSID=""`,
+    `command -v setsid >/dev/null 2>&1 && SETSID=setsid`
+  ];
+  const body = manifest.services.flatMap((svc) => restoreOneService(driveRoot, svc));
+  return [...head, ...body, ``].join(`
+`);
+}
+function servicesDumpScript(manifest, driveRoot) {
+  const withDump = manifest.services.filter((svc) => svc.data?.dump);
+  if (withDump.length === 0)
+    return null;
+  const lines = [
+    `#!/bin/sh`,
+    `# generated by agent-compose — pre-recycle data dumps from .ac/services.yml`,
+    `status() { printf '%s %s %s %s\\n' ${shq(SERVICE_STATUS_PREFIX)} "$1" "$2" "$3"; }`
+  ];
+  for (const svc of withDump) {
+    const cwd = serviceCwd(driveRoot, svc);
+    lines.push(``, `# --- ${svc.name} ---`, `(`, `  cd ${shq(cwd)} || { status ${shq(svc.name)} dump-failed cwd-missing; exit 0; }`, `  if ${shc(svc.data.dump)} > /dev/null 2>&1; then`, `    status ${shq(svc.name)} dumped ''`, `  else`, `    status ${shq(svc.name)} dump-failed ''`, `  fi`, `)`);
+  }
+  lines.push(``);
+  return lines.join(`
+`);
+}
+function parseServicesRestoreOutput(stdout) {
+  const out = [];
+  for (const raw of stdout.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line.startsWith(`${SERVICE_STATUS_PREFIX} `))
+      continue;
+    const rest = line.slice(SERVICE_STATUS_PREFIX.length + 1).trim();
+    const [name, status, ...detail] = rest.split(/\s+/);
+    if (!name || !status)
+      continue;
+    if (!["ok", "unchecked", "failed", "dumped", "dump-failed"].includes(status))
+      continue;
+    const d = detail.join(" ").trim();
+    out.push({ name, status, ...d ? { detail: d } : {} });
+  }
+  return out;
+}
+function formatServicesRestoreSummary(outcomes) {
+  return outcomes.map((o) => {
+    if (o.status === "ok" || o.status === "unchecked" || o.status === "dumped")
+      return `${o.name} ✓`;
+    const why = o.detail ? `${o.detail} — see ${SERVICES_STATE_DIR}/${o.name}.log` : `see ${SERVICES_STATE_DIR}/${o.name}.log`;
+    return `${o.name} ✗ (${why})`;
+  }).join(" ");
+}
 // src/display.ts
 var DISPLAY_MARKER_KEY = "acDisplay";
 var DISPLAY_MARKER_VERSION = "v1";
@@ -7192,6 +8436,7 @@ function clampAskOptions(raw) {
   }
   return options;
 }
+var DESKTOP_NOTE_MAX_CHARS = 200;
 function serializeDisplayMarker(marker) {
   return JSON.stringify({ [DISPLAY_MARKER_KEY]: DISPLAY_MARKER_VERSION, ...marker });
 }
@@ -7277,6 +8522,21 @@ function parseDisplayMarker(line) {
         ...yLabel !== undefined ? { yLabel } : {}
       };
     }
+    case "desktop": {
+      const path = str("path");
+      if (!path || !isPlausibleDrivePath(path))
+        return null;
+      const capturedAt = str("capturedAt");
+      const capturedOk = capturedAt !== undefined && Number.isFinite(Date.parse(capturedAt));
+      const note = str("note");
+      return {
+        kind: "desktop",
+        path,
+        ...str("factorySlug") ? { factorySlug: str("factorySlug") } : {},
+        ...capturedOk ? { capturedAt } : {},
+        ...note !== undefined ? { note: note.slice(0, DESKTOP_NOTE_MAX_CHARS) } : {}
+      };
+    }
     case "ask": {
       const askId = str("askId");
       const rawPrompt = str("prompt");
@@ -7359,7 +8619,8 @@ var VALUE_FLAGS = new Set([
   "--to",
   "--prompt",
   "--options",
-  "--approver"
+  "--approver",
+  "--note"
 ]);
 function isShellControlWord(w) {
   if (/^\d*>&\d+$/.test(w))
@@ -7421,6 +8682,8 @@ function detectAgentcInvocation(command) {
         const path = drivePath(args[2]);
         return path ? { verb: "display-image", path, ...withSlug } : null;
       }
+      case "desktop":
+        return { verb: "display-desktop" };
       case "preview": {
         const path = drivePath(args[2]);
         return path ? { verb: "display-preview", path } : null;
@@ -7574,6 +8837,8 @@ function createDisplayPromoter(ctx = {}) {
           return call("display_plan", {});
         case "display-image":
           return call("display_image", { path: invocation.path, ...factoryRef(invocation.factorySlug) });
+        case "display-desktop":
+          return call("display_desktop", {});
         case "display-preview":
           return call("display_preview", { path: invocation.path, ...factoryRef(undefined) });
         case "display-table":
@@ -7667,6 +8932,17 @@ function createDisplayPromoter(ctx = {}) {
             ...factoryRef(m?.factorySlug ?? inv.factorySlug)
           })];
         }
+        case "display-desktop": {
+          const marker = findDisplayMarker(text);
+          if (marker?.kind !== "desktop")
+            return [result(msg.output)];
+          return [result({
+            path: marker.path,
+            ...factoryRef(marker.factorySlug),
+            capturedAt: marker.capturedAt ?? null,
+            note: marker.note ?? null
+          })];
+        }
         case "display-table": {
           if (inv.source === "file")
             return [result(msg.output)];
@@ -7715,28 +8991,49 @@ function createDisplayPromoter(ctx = {}) {
 export {
   writeTool,
   writeAgentContext,
+  wrapMidTurnUserMessage,
+  uniquePromptPath,
+  turnLivenessProbeCommand,
+  streamInputFeederFragment,
   stepInputPath,
+  standalonePerfProbeCommand,
   snapshotResolves,
   shellWords,
+  shellQuote,
+  sessionEnvSourceFragment,
+  servicesRestoreScript,
+  servicesDumpScript,
   serveStep,
   serializeDisplayMarker,
   sandboxSizeLabel,
+  runnerBusySentinelFragment,
   runWorkflowSteps,
   runWorkflowSingleStep,
   runWorkflow,
   runProcessorChain,
   resolveSdkAlias,
+  residentResultCountCommand,
+  residentIdleWatchdogFragment,
+  residentIdleCheckFragment,
+  residentFeederFragment,
   requireScope,
   requestPauseAndAwait,
   requestContextPath,
+  renderServicesManifest,
   renderDirectiveMarker,
   redactPattern,
   reconnectStep,
   reconnectSandbox,
   readTool,
+  perfSamplerFunctionFragment,
+  parseTurnProbeOutput,
   parseStepResult,
   parseSseStream,
   parseSseExecStream,
+  parseServicesRestoreOutput,
+  parseServicesManifest,
+  parsePerfToken,
+  parsePerfProbeOutput,
   parseNameVersion,
   parseDisplayMarker,
   parseDirectiveMarkers,
@@ -7748,6 +9045,7 @@ export {
   normalizeConversationStreamEvent,
   makeSandboxProvider,
   makeDesktopSandboxProvider,
+  livenessVerdictFromReading,
   listVercelRuntimeModels,
   listOwnedSandboxes,
   launchStep,
@@ -7759,13 +9057,19 @@ export {
   isPlatformE2bTemplateAlias,
   isE2bSupportedSize,
   invokeStep,
+  installDesktopOpenCmd,
+  installChromiumDefaultsCmd,
+  injectAppendAndAckCommand,
   importSourceModule,
   humanApproval,
   getSandboxQuotas,
+  formatServicesRestoreSummary,
   formatError,
   findDisplayMarker,
   explainBundleFailure,
+  exitEventPushCommand,
   editTool,
+  e2bMaxSandboxMs,
   e2bMachineSpec,
   e2bDevboxTemplateRef,
   e2bBaseTemplate,
@@ -7779,8 +9083,10 @@ export {
   defineStep,
   defineSandboxEnvironment,
   defineRuntime,
+  deferredExitEventPushCommand,
   cursorSpec,
   cursor_default as cursorRuntime,
+  credEnvSourceFragment,
   createVercelRuntime,
   createSandbox,
   createOpencodeRuntime,
@@ -7810,6 +9116,8 @@ export {
   buildInvokeChild,
   buildAgentContextDoc,
   buildAddedSessionBrief,
+  browserBackfillStatusCmd,
+  browserBackfillCmd,
   bashTool,
   assertDefaultExportIsDefineWorkflow,
   amp_default as ampRuntime,
@@ -7822,6 +9130,7 @@ export {
   Verdict,
   VercelRunner,
   VERCEL_MEMORY_MB_PER_VCPU,
+  TURN_PROBE_TIMEOUT_MS,
   TMP_DIR,
   TABLE_MAX_ROWS,
   TABLE_MAX_COLUMNS,
@@ -7832,7 +9141,14 @@ export {
   STEP_RESULT_PREFIX,
   STEP_PAUSE_PREFIX,
   STEP_ENV,
+  SESSION_ENV_FILE_RELPATH,
   SESSION_DEFAULT_SANDBOX_SIZE,
+  SERVICE_STATUS_PREFIX,
+  SERVICE_NAME_RE,
+  SERVICE_HEALTH_TIMEOUT_S,
+  SERVICES_STATE_DIR,
+  SERVICES_MAX,
+  SERVICES_MANIFEST_RELPATH,
   SDK_SPECIFIER_ALIASES,
   SDK_PACKAGE,
   SANDBOX_VCPUS,
@@ -7841,18 +9157,29 @@ export {
   SANDBOX_MACHINES,
   ReservedKeyError,
   RequestContext,
+  RUNNER_HEARTBEAT_STALE_MS,
+  RUNNER_HEARTBEAT_INTERVAL_SECONDS,
   RUNNER_COMMAND,
   RUNNER_BUNDLE_PATH,
   REVISION_SELECTOR_RE,
+  RESIDENT_WATCHDOG_POLL_S,
+  RESIDENT_RESULT_LINE_PREFIX,
+  RESIDENT_IDLE_TTL_S,
   PauseSchemaError,
   PauseRequestError,
   PauseExpiredError,
   PauseError,
   PLAN_MAX_ENTRIES,
   PLAN_ENTRY_MAX_CHARS,
+  PERF_TOKEN_MAX_CHARS,
+  PERF_SAMPLE_EVERY_BEATS,
+  PERF_PROBE_WINDOW_SECONDS,
   NonSerialisableValueError,
   MAX_DIRECTIVES_PER_OUTPUT,
+  LAUNCH_EXEC_TIMEOUT_MS,
   LATEST_VERSION,
+  INSTALL_PROBE_TIMEOUT_MS,
+  INJECT_ACK_EXEC_TIMEOUT_MS,
   EngineError,
   E2B_TEMPLATE_SIZES,
   E2B_MAX_VCPUS,
@@ -7865,15 +9192,23 @@ export {
   DISPLAY_MARKER_KEY,
   DIRECTIVE_MARKER_SUFFIX,
   DIRECTIVE_MARKER_PREFIX,
+  DESKTOP_NOTE_MAX_CHARS,
   DEFAULT_SANDBOX_SIZE,
   DEFAULT_CLAUDE_MODEL,
   ClaudeRunner,
+  CLI_INSTALL_TIMEOUT_MS,
   CLAUDE_CODE_EFFORT_LEVELS,
   CLAUDE_CODE_ACP_ADAPTER,
+  CHROMIUM_DEFAULTS_PATH,
+  CHROMIUM_DEFAULTS,
   CHART_MAX_SERIES,
   CHART_MAX_POINTS_PER_SERIES,
   CHART_LABEL_MAX_CHARS,
   BUNDLER_VERSION,
+  BROWSER_INSTALL_IN_PROGRESS_MSG,
+  BROWSER_BACKFILL_PIDFILE,
+  BROWSER_BACKFILL_LOG,
+  BROWSER_BACKFILL_FAILED,
   AgentStatusSchema,
   AgentMessageSchema,
   AgentComposeError,
@@ -7897,6 +9232,11 @@ export {
   AC_RUN_ID,
   AC_RESERVED_PREFIX,
   AC_PARENT_RUN_ID,
+  AC_OPEN_STATE_DIR,
+  AC_OPEN_SHIM_PATHS,
+  AC_OPEN_SHIM,
+  AC_OPEN_SCRIPT,
+  AC_OPEN_PATH,
   AC_FACTORY_ID,
   AC_API_KEY_SCOPES,
   AC_ABORT_SIGNAL,