@agent-compose/sdk 0.8.1 → 0.8.3

package/src/agent/perf-sampler.ts

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

package/src/agent/services-manifest.ts

@@ -0,0 +1,356 @@
+/**
+ * The durable services manifest — `.ac/services.yml` on the session's drive
+ * branch.
+ *
+ * Sessions run on cattle machines: a VM recycle (resize, eviction, failed
+ * reconnect) discards every process and every byte off the drive. The manifest
+ * is the pet — a small, versioned description of the long-running services a
+ * session depends on (dev servers, docker compose stacks, built dashboards) so
+ * the platform can rebuild the stack on a fresh machine without being asked.
+ *
+ * This module is pure string/data work: a parser for a deliberately RESTRICTED
+ * YAML subset (no yaml dependency — the schema is small and fixed, and a
+ * hand-rolled parser matches house style, cf. parseRecorderStatus /
+ * parsePerfToken), a serializer the CLI uses for `agentc services add/remove`,
+ * and the shared types. Script generation lives in ./services-restore.ts.
+ *
+ * Supported YAML subset (anything else is a loud parse error, never a guess):
+ *
+ *   version: 1
+ *   services:
+ *     - name: postgres
+ *       command: docker compose up postgres     # required, foreground shell
+ *       cwd: myapp                              # optional, relative to drive root
+ *       port: 5432                              # optional, informational + docs
+ *       env: reads DATABASE_URL from .env       # optional free-text note
+ *       setup: docker compose pull postgres     # optional one-time prep per machine
+ *       health:                                 # optional, at most one of:
+ *         cmd: pg_isready -h localhost          #   shell probe (exit 0 = healthy)
+ *         http: http://localhost:5432/          #   or an HTTP 2xx probe
+ *       data:                                   # optional data hooks
+ *         dump: pg_dump app > .ac/seeds/dev.sql     # before a DELIBERATE recycle
+ *         restore: psql app < .ac/seeds/dev.sql     # after setup on a fresh boot
+ *
+ * Scalars only, one nesting level (`health:` / `data:`), full-line `#` comments
+ * only (an inline ` # ...` would be ambiguous inside shell commands and is kept
+ * as part of the value), no multi-line block scalars (`|` / `>`), no anchors,
+ * no flow collections.
+ */
+
+export const SERVICES_MANIFEST_RELPATH = ".ac/services.yml";
+
+/** Hard cap on manifest entries — a manifest is a stack, not a fleet. */
+export const SERVICES_MAX = 16;
+
+export const SERVICE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,31}$/;
+
+export interface ServiceHealth {
+  /** Shell probe; exit 0 means healthy. Mutually exclusive with `http`. */
+  cmd?: string;
+  /** HTTP probe; any 2xx means healthy. Mutually exclusive with `cmd`. */
+  http?: string;
+}
+
+export interface ServiceDataHooks {
+  /**
+   * Run before a DELIBERATE recycle (resize). Evictions and dead-VM
+   * fresh-acquires cannot run it — the machine is already gone — so dumps are
+   * a courtesy, not a guarantee; durable data belongs on the drive.
+   */
+  dump?: string;
+  /** Run after `setup` on a fresh boot, before the service launches. */
+  restore?: string;
+}
+
+export interface ServiceEntry {
+  name: string;
+  /** Foreground shell command; launched detached with durable log + pidfile. */
+  command: string;
+  /** Working directory, relative to the drive root (absolute rejected). */
+  cwd?: string;
+  /** Informational — surfaced in `agentc services list` and the restore line. */
+  port?: number;
+  /** Free-text note about env the service expects (documentation only). */
+  env?: string;
+  /** One-time per-machine prep (e.g. `docker compose up -d`). */
+  setup?: string;
+  health?: ServiceHealth;
+  data?: ServiceDataHooks;
+}
+
+export interface ServicesManifest {
+  version: 1;
+  services: ServiceEntry[];
+}
+
+export interface ParseServicesManifestResult {
+  /** Present iff `errors` is empty. All-or-nothing: a broken manifest restores nothing, loudly. */
+  manifest: ServicesManifest | null;
+  errors: string[];
+}
+
+const TOP_KEYS = new Set(["version", "services"]);
+const ENTRY_KEYS = new Set(["name", "command", "cwd", "port", "env", "setup", "health", "data"]);
+const HEALTH_KEYS = new Set(["cmd", "http"]);
+const DATA_KEYS = new Set(["dump", "restore"]);
+
+interface Line {
+  no: number;
+  indent: number;
+  /** True when the content starts with `- ` (a sequence item). */
+  dash: boolean;
+  /** Content with indentation (and any leading `- `) stripped. */
+  text: string;
+}
+
+function lex(text: string): Line[] {
+  const out: Line[] = [];
+  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;
+}
+
+/** Split `key: value` (value may be empty for map openers). Null when the line is not a mapping. */
+function splitKey(text: string): { key: string; value: string } | null {
+  if (text.endsWith(":") && !text.includes(": ")) {
+    const key = text.slice(0, -1).trim();
+    return /^[A-Za-z_][\w-]*$/.test(key) ? { key, 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() };
+}
+
+/** Unquote a scalar. Only full single/double quoting is recognized. */
+function scalar(value: string, no: number, errors: string[]): string {
+  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;
+}
+
+export function parseServicesManifest(text: string): ParseServicesManifestResult {
+  const errors: string[] = [];
+  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: number | null = null;
+  const services: ServiceEntry[] = [];
+  let current: ServiceEntry | null = null;
+  let currentIndent = -1;
+  /** "health" | "data" while inside a nested map, else null. */
+  let nested: "health" | "data" | null = null;
+  let nestedIndent = -1;
+  let inServices = false;
+
+  const finish = (entry: ServiceEntry | null) => {
+    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;
+    }
+
+    // Top-level keys.
+    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;
+    }
+
+    // New sequence item.
+    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;
+    }
+
+    // Nested map keys (health/data), recognized by deeper indentation.
+    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 value = scalar(kv.value, line.no, errors);
+      if (value === "") {
+        errors.push(`line ${line.no}: \`${nested}.${kv.key}\` needs a value`);
+        continue;
+      }
+      const bucket = (current[nested] ??= {});
+      (bucket as Record<string, string>)[kv.key] = value;
+      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 as unknown as Record<string, string>)[kv.key] = value;
+  }
+  finish(current);
+
+  // Semantic validation.
+  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<string>();
+  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: [] };
+}
+
+/** Quote a scalar for emission iff the parser would otherwise mangle it. */
+function emitScalar(value: string): string {
+  const needsQuote =
+    value !== value.trim() ||
+    value.startsWith("'") ||
+    value.startsWith('"') ||
+    value === "|" ||
+    value === ">" ||
+    value.startsWith("| ") ||
+    value.startsWith("> ");
+  if (!needsQuote) return value;
+  return `"${value.replace(/([\\"])/g, "\\$1")}"`;
+}
+
+/**
+ * Serialize a manifest in the canonical shape the parser reads back.
+ * Values containing newlines are a caller bug (the CLI rejects them first).
+ */
+export function renderServicesManifest(manifest: ServicesManifest): string {
+  const out: string[] = [
+    "# 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("\n") + "\n";
+}