@humwick/runner 0.0.0-stage → 0.130.1

package/src/session-scratch.ts

@@ -0,0 +1,296 @@
+import { accessSync, appendFileSync, constants, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { chmod, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { sanitizeFsName } from "@humwick/sdk/fs-name";
+import { spawnSyncBounded } from "./bounded-spawn-sync";
+
+const SCRATCH_DIR_NAME = ".agent-relay";
+// The local-ignore entry. Leading + trailing slash scopes it to the dir at the
+// base, matching git's gitignore semantics.
+const EXCLUDE_ENTRY = "/.agent-relay/";
+const LAUNCHER_DIR = join(tmpdir(), `agent-relay-launchers-${typeof process.getuid === "function" ? process.getuid() : "user"}`);
+const DEFAULT_LAUNCHER_SWEEP_MIN_AGE_MS = 24 * 60 * 60 * 1000;
+
+export interface SessionScratchLayout {
+  baseDir: string; // dir that contains .agent-relay (cwd, or fallback base dir)
+  rootDir: string; // <base>/.agent-relay
+  sessionsDir: string; // <base>/.agent-relay/sessions
+  sessionDir: string; // <base>/.agent-relay/sessions/<id>
+  tmpDir: string; // <base>/.agent-relay/sessions/<id>/tmp
+  replyFile: string; // <tmp>/reply.md
+}
+
+interface SessionScratchTarget {
+  agentId: string;
+  cwd: string;
+  // Orchestrator base dir, used only when cwd is not writable. NEVER home — a
+  // home fallback would place scratch above the orchestrator base dir and break
+  // cwd containment.
+  fallbackBaseDir?: string;
+}
+
+interface SessionLauncherTarget {
+  launcherScript?: string;
+  launcherDir?: string;
+  tmuxSession?: string;
+}
+
+function isWritableDir(dir: string): boolean {
+  try {
+    if (!statSync(dir).isDirectory()) return false;
+    accessSync(dir, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Prefer cwd; fall back to the orchestrator base dir only when cwd is not a
+// writable dir. Returns cwd as a last resort so callers can still attempt mkdir
+// (and surface the real error) rather than silently picking an unrelated path.
+export function resolveScratchBase(cwd: string, fallbackBaseDir?: string): string {
+  if (isWritableDir(cwd)) return cwd;
+  if (fallbackBaseDir && isWritableDir(fallbackBaseDir)) return fallbackBaseDir;
+  return cwd;
+}
+
+function sessionScratchLayout(baseDir: string, agentId: string): SessionScratchLayout {
+  const rootDir = join(baseDir, SCRATCH_DIR_NAME);
+  const sessionsDir = join(rootDir, "sessions");
+  const sessionDir = join(sessionsDir, agentId);
+  const tmpDir = join(sessionDir, "tmp");
+  return { baseDir, rootDir, sessionsDir, sessionDir, tmpDir, replyFile: join(tmpDir, "reply.md") };
+}
+
+// Resolve git's exclude file for baseDir, correctly handling plain repos,
+// worktrees, and submodules (git rev-parse returns the shared commondir's
+// info/exclude). Returns null when baseDir is not inside a git work tree.
+function gitExcludePath(baseDir: string): string | null {
+  try {
+    const result = spawnSyncBounded(["git", "-C", baseDir, "rev-parse", "--git-path", "info/exclude"], {
+      stdin: "ignore", stdout: "pipe", stderr: "ignore",
+    });
+    if (result.exitCode !== 0) return null;
+    const out = result.stdout.toString().trim();
+    if (!out) return null;
+    return isAbsolute(out) ? out : resolve(baseDir, out);
+  } catch {
+    return null;
+  }
+}
+
+// Idempotently append EXCLUDE_ENTRY to an ignore file (grep-before-write).
+function appendIgnoreEntry(file: string): void {
+  let existing = "";
+  try {
+    existing = readFileSync(file, "utf8");
+  } catch {}
+  const wanted = EXCLUDE_ENTRY.trim();
+  if (existing.split("\n").some((line) => line.trim() === wanted)) return;
+  mkdirSync(dirname(file), { recursive: true });
+  const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  appendFileSync(file, `${prefix}${EXCLUDE_ENTRY}\n`);
+}
+
+// Ensure `.agent-relay/` is locally ignored. Prefers .git/info/exclude (git's
+// local, uncommitted ignore list) so no tracked file is ever modified; falls
+// back to .gitignore only when baseDir is not a git repo. Returns which file was
+// used (for logging/tests).
+export function ensureScratchIgnored(baseDir: string): "exclude" | "gitignore" {
+  const excludePath = gitExcludePath(baseDir);
+  if (excludePath) {
+    appendIgnoreEntry(excludePath);
+    return "exclude";
+  }
+  appendIgnoreEntry(join(baseDir, ".gitignore"));
+  return "gitignore";
+}
+
+// SessionStart: create the session tmp dir and ensure local ignore. Dir
+// creation is the load-bearing part; ignore setup is best-effort.
+//
+// #2310 P1 — this dir can hold sensitive spilled content (an over-cap memory/continuation
+// injection's full text, #1935's monitor over-limit handling), so it's session-private: 0700, not
+// the default (umask-dependent, typically 0755/0775). `mode` here is safe from umask stripping it
+// back down: umask can only CLEAR bits from the requested mode, and 0700 already has none of the
+// group/other bits a realistic umask would clear — so this always lands exactly on 0700, with no
+// separate chmod needed (avoiding both a redundant blocking call and a chmod-vs-mkdir TOCTOU gap).
+export function ensureSessionScratch(target: SessionScratchTarget): SessionScratchLayout {
+  const base = resolveScratchBase(target.cwd, target.fallbackBaseDir);
+  const layout = sessionScratchLayout(base, target.agentId);
+  mkdirSync(layout.tmpDir, { recursive: true, mode: 0o700 });
+  try {
+    ensureScratchIgnored(base);
+  } catch {
+    // best-effort: a missing ignore entry never pollutes git because the dir is
+    // already created and the entry is the only thing at risk.
+  }
+  return layout;
+}
+
+function resolveLauncherDir(launcherDir?: string): string {
+  return launcherDir ?? LAUNCHER_DIR;
+}
+
+export function launcherScriptPathForSession(sessionName: string, launcherDir?: string): string {
+  const sanitized = sanitizeFsName(sessionName, { replacement: "-", collapse: false });
+  return join(resolveLauncherDir(launcherDir), `${sanitized}.sh`);
+}
+
+// Named-pipe path the launcher script blocks on before exec'ing the real provider
+// command (#1317) — lets the caller attach `tmux pipe-pane` while the pane is still
+// idle, so a process that exits within milliseconds can't slip output past it.
+export function launcherGatePathForSession(sessionName: string, launcherDir?: string): string {
+  return `${launcherScriptPathForSession(sessionName, launcherDir)}.gate`;
+}
+
+/** Stage a transient provider's one-shot user assignment before its session starts. */
+export async function stageOneShotPrompt(stdinFile: string, exitCodeFile: string, prompt: string): Promise<void> {
+  await writeFile(stdinFile, prompt, { mode: 0o600 });
+  await chmod(stdinFile, 0o600);
+  await rm(exitCodeFile, { force: true });
+}
+
+/** Missing is deliberately distinct from a clean exit: the launcher may have been killed. */
+export async function readOneShotExitCode(exitCodeFile: string): Promise<string | undefined> {
+  try { return (await readFile(exitCodeFile, "utf8")).trim(); } catch { return undefined; }
+}
+
+function dedupeBases(bases: Array<string | undefined>): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const b of bases) {
+    if (!b || seen.has(b)) continue;
+    seen.add(b);
+    out.push(b);
+  }
+  return out;
+}
+
+function dedupePaths(paths: Array<string | undefined>): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const path of paths) {
+    if (!path || seen.has(path)) continue;
+    seen.add(path);
+    out.push(path);
+  }
+  return out;
+}
+
+// SessionEnd: remove this session's dir from every candidate base.
+export function reapSessionScratch(target: SessionScratchTarget): void {
+  for (const base of dedupeBases([target.cwd, target.fallbackBaseDir])) {
+    const { sessionDir } = sessionScratchLayout(base, target.agentId);
+    try {
+      rmSync(sessionDir, { recursive: true, force: true });
+    } catch {}
+  }
+}
+
+// Claude headless sessions externalize their provider launch command into a
+// per-session script under /tmp. Remove it on runner shutdown alongside the
+// scratch dir reap to avoid leaking one file per spawn.
+export function reapSessionLauncher(target: SessionLauncherTarget): string[] {
+  const removed: string[] = [];
+  for (const path of dedupePaths([
+    target.launcherScript,
+    target.tmuxSession ? launcherScriptPathForSession(target.tmuxSession, target.launcherDir) : undefined,
+    target.tmuxSession ? launcherGatePathForSession(target.tmuxSession, target.launcherDir) : undefined,
+  ])) {
+    try {
+      const exists = statSync(path).isFile();
+      rmSync(path, { force: true });
+      if (exists) removed.push(path);
+    } catch {}
+  }
+  return removed;
+}
+
+interface SweepOptions {
+  cwd: string;
+  fallbackBaseDir?: string;
+  // Agent ids to keep (currently-known agents + self). Any session dir whose id
+  // is not in this set AND older than minAgeMs is removed.
+  keepAgentIds: Set<string>;
+  now: number;
+  minAgeMs?: number;
+  /** Caps a single background pass so a historical buildup cannot monopolize I/O. */
+  maxEntries?: number;
+}
+
+interface LauncherSweepOptions {
+  // Agent ids to keep (currently-known agents + self). Launcher scripts embed
+  // AGENT_RELAY_ID, so a stale sweep can safely remove only scripts whose agent
+  // is no longer live.
+  keepAgentIds: Set<string>;
+  launcherDir?: string;
+  now: number;
+  minAgeMs?: number;
+  maxEntries?: number;
+}
+
+function maybeShellUnquote(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("'") || !trimmed.endsWith("'")) return trimmed;
+  return trimmed.slice(1, -1).replace(/'\\''/g, "'");
+}
+
+async function launcherAgentId(scriptPath: string): Promise<string | null> {
+  try {
+    const match = (await Bun.file(scriptPath).text()).match(/^export AGENT_RELAY_ID=(.+)$/m);
+    if (!match) return null;
+    const agentId = maybeShellUnquote(match[1] ?? "");
+    return agentId || null;
+  } catch {
+    return null;
+  }
+}
+
+// Periodic, bounded sweep of leftover session dirs from agents no longer known to the
+// relay. The minAge grace avoids racing a peer that just created its dir but has not yet
+// appeared in the agent list.
+export async function sweepStaleSessionsAsync(opts: SweepOptions): Promise<string[]> {
+  const minAge = opts.minAgeMs ?? 60 * 60 * 1000;
+  const maxEntries = opts.maxEntries ?? 100;
+  const removed: string[] = [];
+  for (const base of dedupeBases([opts.cwd, opts.fallbackBaseDir])) {
+    const sessionsDir = join(base, SCRATCH_DIR_NAME, "sessions");
+    let ids: string[];
+    try { ids = await readdir(sessionsDir); } catch { continue; }
+    for (const id of ids.slice(0, maxEntries)) {
+      if (opts.keepAgentIds.has(id)) continue;
+      const dir = join(sessionsDir, id);
+      try {
+        if (opts.now - (await stat(dir)).mtimeMs < minAge) continue;
+        await rm(dir, { recursive: true, force: true });
+        removed.push(dir);
+      } catch {}
+    }
+  }
+  return removed;
+}
+
+// Periodic, bounded sweep of leaked per-spawn launcher scripts. Old scripts whose agent
+// id is no longer live are safe to prune; old unparsable files are treated as stale too.
+export async function sweepStaleLaunchersAsync(opts: LauncherSweepOptions): Promise<string[]> {
+  const minAge = opts.minAgeMs ?? DEFAULT_LAUNCHER_SWEEP_MIN_AGE_MS;
+  const maxEntries = opts.maxEntries ?? 100;
+  const removed: string[] = [];
+  const launcherDir = resolveLauncherDir(opts.launcherDir);
+  let entries: string[];
+  try { entries = await readdir(launcherDir); } catch { return removed; }
+  for (const entry of entries.slice(0, maxEntries)) {
+    const scriptPath = join(launcherDir, entry);
+    try {
+      const current = await stat(scriptPath);
+      if (!current.isFile() || opts.now - current.mtimeMs < minAge) continue;
+      const agentId = await launcherAgentId(scriptPath);
+      if (agentId && opts.keepAgentIds.has(agentId)) continue;
+      await rm(scriptPath, { force: true });
+      removed.push(scriptPath);
+    } catch {}
+  }
+  return removed;
+}

package/src/spawn-input.ts

@@ -0,0 +1,147 @@
+import { basename } from "node:path";
+import { isatty } from "node:tty";
+import { LAUNCH_MODES, isLaunchMode, type LaunchMode, type SpawnProvider } from "@humwick/sdk";
+import { parseResolvedModelRecord, type ResolvedModelRecord } from "@humwick/sdk/provider-catalog";
+import { getAllManifests } from "@humwick/providers";
+
+export interface RunnerCliOptions {
+  provider: SpawnProvider;
+  model?: string;
+  effort?: string;
+  /** #2595 — effective-catalog window resolved server-side; preferred over the static manifest. */
+  contextWindowTokens?: number;
+  /** #2599 — the full server-resolved model record (protocol ≥ 2); precedence payload > manifest. */
+  modelRecord?: ResolvedModelRecord;
+  headless: boolean;
+  interactive: boolean;
+  /** #2773 — interactive|headless driver; absent keeps the provider's legacy selection. */
+  launchMode?: LaunchMode;
+  cwd?: string;
+  rig?: string;
+  profile?: string;
+  relayUrl?: string;
+  token?: string;
+  approvalMode?: string;
+  label?: string;
+  agentId?: string;
+  prompt?: string;
+  systemPromptAppend?: string;
+  tags: string[];
+  caps: string[];
+  providerArgs: string[];
+  help: boolean;
+}
+
+function detectProviderFromBin(argv: string[], processBin = process.env._): SpawnProvider {
+  const bin = [argv[1], processBin].map((s) => basename(s || "")).join(" ");
+  for (const manifest of getAllManifests()) {
+    if (bin.includes(manifest.id)) return manifest.id as SpawnProvider;
+  }
+  return getAllManifests()[0]?.id as SpawnProvider ?? "claude";
+}
+
+function isRegisteredProvider(value: string): value is SpawnProvider {
+  return getAllManifests().some((manifest) => manifest.id === value);
+}
+
+function csvSplit(value: string): string[] {
+  return value.split(",").map((part) => part.trim()).filter(Boolean);
+}
+
+/** Pure runner argv parsing shared by the production CLI and effective-launch harness. */
+export function parseRunnerCliArgs(
+  argv: string[],
+  options: { stdinIsTty?: boolean; processBin?: string } = {},
+): RunnerCliOptions {
+  let provider = detectProviderFromBin(argv, options.processBin);
+  const relayArgs = argv.slice(2);
+  const providerSep = relayArgs.indexOf("--");
+  const ownArgs = providerSep >= 0 ? relayArgs.slice(0, providerSep) : relayArgs;
+  const providerArgs = providerSep >= 0 ? relayArgs.slice(providerSep + 1) : [];
+  let headless = false;
+  let launchMode: LaunchMode | undefined;
+  let help = false;
+  let model: string | undefined;
+  let effort: string | undefined;
+  let contextWindowTokens: number | undefined;
+  // #2599 — raw --model-record-* fields, assembled then parsed ONCE through the shared parser
+  // (the same parser the orchestrator uses), so CLI parsing can never drift from the payload seam.
+  const modelRecordRaw: Record<string, unknown> = {};
+  let cwd: string | undefined;
+  let rig: string | undefined;
+  let profile: string | undefined;
+  let relayUrl: string | undefined;
+  let token: string | undefined;
+  let approvalMode: string | undefined;
+  let label: string | undefined;
+  let agentId: string | undefined;
+  let prompt: string | undefined;
+  let systemPromptAppend: string | undefined;
+  let tags: string[] = [];
+  let caps: string[] = [];
+
+  for (let i = 0; i < ownArgs.length; i += 1) {
+    const arg = ownArgs[i];
+    if (arg && isRegisteredProvider(arg)) provider = arg;
+    else if (arg === "--headless") headless = true;
+    else if (arg === "--launch-mode" && ownArgs[i + 1]) {
+      const value = ownArgs[++i];
+      if (!isLaunchMode(value)) throw new Error(`--launch-mode must be one of: ${LAUNCH_MODES.join(", ")}`);
+      launchMode = value;
+    }
+    else if (arg === "--model" && ownArgs[i + 1]) model = ownArgs[++i];
+    else if (arg === "--effort" && ownArgs[i + 1]) effort = ownArgs[++i];
+    // #2595 — server-resolved effective-catalog window; positive-integer gate keeps a malformed
+    // value from ever becoming a fabricated denominator (openCodeContextState would clamp anyway).
+    else if (arg === "--context-window-tokens" && ownArgs[i + 1]) {
+      const parsed = Number(ownArgs[++i]);
+      contextWindowTokens = Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+    }
+    // #2599 — full-record fields (protocol ≥ 2). Values ride raw; the shared parser at the end
+    // applies the SAME gates as the orchestrator seam. --model-record-threshold carries a JSON
+    // threshold object; a malformed JSON is untrusted and drops the whole record field set to
+    // the parser's verdict (never a fabricated threshold).
+    else if (arg === "--model-record-alias" && ownArgs[i + 1]) modelRecordRaw.alias = ownArgs[++i];
+    else if (arg === "--model-record-provider-model" && ownArgs[i + 1]) modelRecordRaw.providerModel = ownArgs[++i];
+    else if (arg === "--model-record-qualified" && ownArgs[i + 1]) modelRecordRaw.qualifiedModel = ownArgs[++i];
+    else if (arg === "--model-record-effort" && ownArgs[i + 1]) modelRecordRaw.effort = ownArgs[++i];
+    else if (arg === "--model-record-window" && ownArgs[i + 1]) {
+      const parsed = Number(ownArgs[++i]);
+      if (Number.isSafeInteger(parsed) && parsed > 0) modelRecordRaw.contextWindowTokens = parsed;
+    }
+    else if (arg === "--model-record-max-output" && ownArgs[i + 1]) {
+      const parsed = Number(ownArgs[++i]);
+      if (Number.isSafeInteger(parsed) && parsed > 0) modelRecordRaw.maxOutputTokens = parsed;
+    }
+    else if (arg === "--model-record-threshold" && ownArgs[i + 1]) {
+      try {
+        const parsed = JSON.parse(ownArgs[++i]!) as unknown;
+        if (parsed !== undefined) modelRecordRaw.contextThreshold = parsed;
+      } catch {
+        // Malformed threshold JSON is untrusted — omit it; the record still parses without it.
+      }
+    }
+    else if (arg === "--cwd" && ownArgs[i + 1]) cwd = ownArgs[++i];
+    else if (arg === "--rig" && ownArgs[i + 1]) rig = ownArgs[++i];
+    else if (arg === "--profile" && ownArgs[i + 1]) profile = ownArgs[++i];
+    else if (arg === "--relay-url" && ownArgs[i + 1]) relayUrl = ownArgs[++i];
+    else if (arg === "--token" && ownArgs[i + 1]) token = ownArgs[++i];
+    else if ((arg === "--approval" || arg === "--approval-mode") && ownArgs[i + 1]) approvalMode = ownArgs[++i];
+    else if (arg === "--label" && ownArgs[i + 1]) label = ownArgs[++i];
+    else if (arg === "--agent-id" && ownArgs[i + 1]) agentId = ownArgs[++i];
+    else if (arg === "--prompt" && ownArgs[i + 1]) prompt = ownArgs[++i];
+    else if ((arg === "--system-prompt-append" || arg === "--append-system-prompt") && ownArgs[i + 1]) systemPromptAppend = ownArgs[++i];
+    else if (arg === "--tags" && ownArgs[i + 1]) tags = csvSplit(ownArgs[++i]!);
+    else if (arg === "--caps" && ownArgs[i + 1]) caps = csvSplit(ownArgs[++i]!);
+    else if (arg === "--help" || arg === "-h") help = true;
+    else if (arg !== undefined) providerArgs.push(arg);
+  }
+
+  const interactive = !headless && (options.stdinIsTty ?? isatty(0));
+  const modelRecord = Object.keys(modelRecordRaw).length ? parseResolvedModelRecord(modelRecordRaw) : undefined;
+  return { provider, model, effort, ...(contextWindowTokens !== undefined ? { contextWindowTokens } : {}), ...(modelRecord ? { modelRecord } : {}), headless, interactive, ...(launchMode ? { launchMode } : {}), cwd, rig, profile, relayUrl, token, approvalMode, label, agentId, prompt, systemPromptAppend, tags, caps, providerArgs, help };
+}
+
+export function runnerHelp(provider: string): string {
+  return `${provider}-relay [--headless] [--launch-mode interactive|headless] [--model ALIAS] [--effort LEVEL] [--context-window-tokens N] [--model-record-alias A --model-record-provider-model M --model-record-qualified Q --model-record-effort E --model-record-window N --model-record-max-output N --model-record-threshold JSON] [--rig NAME] [--profile NAME] [--cwd PATH] [--relay-url URL] [--approval MODE] [--label NAME] [--agent-id ID] [--prompt TEXT] [--system-prompt-append TEXT] [--tags a,b] [--caps x,y] [-- provider-args...]`;
+}

package/src/startup-config-fetch.ts

@@ -0,0 +1,48 @@
+import { ReconnectionManager, RELAY_TOKEN_HEADER, errMessage } from "@humwick/sdk";
+import type { SettingEntry } from "@humwick/sdk";
+import { isRetryableTransportError } from "./transport-errors";
+
+export interface StartupFetchDeps {
+  deadlineAt?: number;
+  now: () => number;
+  sleep: (ms: number) => Promise<unknown>;
+  reconnect: Pick<ReconnectionManager, "nextDelay">;
+}
+
+class TransientHubError extends Error {}
+
+function transient(error: unknown): boolean {
+  return error instanceof TransientHubError || isRetryableTransportError(error)
+    || (error instanceof Error && error.name === "TimeoutError");
+}
+
+// Use registration's backoff and initial-handshake budget for managed bootstrap reads (#3326).
+export async function fetchStartupConfig(url: URL, token: string | undefined, timeoutMs: number, deps: Partial<StartupFetchDeps> = {}) {
+  const d = { now: Date.now, sleep: Bun.sleep, reconnect: new ReconnectionManager(), ...deps };
+  const deadline = d.deadlineAt ?? d.now() + timeoutMs;
+  for (;;) {
+    if (d.deadlineAt !== undefined && d.now() >= deadline) throw new Error("provider config retry budget expired");
+    try {
+      const response = await fetch(url, {
+        headers: token ? { [RELAY_TOKEN_HEADER]: token } : undefined,
+        signal: AbortSignal.timeout(timeoutMs > 0 ? Math.max(1, Math.min(5_000, deadline - d.now())) : 5_000),
+      });
+      if (response.status >= 500) {
+        await response.body?.cancel();
+        throw new TransientHubError(`HTTP ${response.status}`);
+      }
+      const body = await response.json().catch((error: unknown) => {
+        if (response.ok && transient(error)) throw error;
+        return null;
+      }) as (Partial<SettingEntry> & { error?: string }) | null;
+      return { response, body };
+    } catch (error) {
+      const remaining = deadline - d.now();
+      if (!transient(error) || remaining <= 0) throw error;
+      const delay = Math.min(d.reconnect.nextDelay(), remaining);
+      console.warn(`[agent-relay] provider config relay read failed (${errMessage(error)}); retrying in ${delay}ms.`);
+      await d.sleep(delay);
+      if (d.now() >= deadline) throw error;
+    }
+  }
+}

package/src/subreaper.ts

@@ -0,0 +1,113 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dlopen } from "bun:ffi";
+import { SYSTEMD_MANAGED_SESSION_PREFIX } from "@humwick/sdk/systemd-unit";
+
+const REAP_INTERVAL_MS = 5_000;
+const ZOMBIE_GRACE_MS = 5_000;
+let reaperStarted = false;
+
+export function hasSystemdSessionOwner(cgroup: string, parentComm: string): boolean {
+  if (parentComm.trim() !== "systemd") return false;
+  return cgroup.split("\n").some((line) => line.startsWith("0::/") && line.slice(4).split("/").some((part) =>
+    part.startsWith(SYSTEMD_MANAGED_SESSION_PREFIX)
+    && part.length > SYSTEMD_MANAGED_SESSION_PREFIX.length + ".service".length
+    && part.endsWith(".service")));
+}
+
+function zombieChildren(): Map<number, string> {
+  const zombies = new Map<number, string>();
+  // A process may fork from any Bun thread. The per-thread children files avoid
+  // reading every process on a busy host for every managed runner.
+  for (const tid of readdirSync("/proc/self/task")) {
+    let children: string;
+    try { children = readFileSync(`/proc/self/task/${tid}/children`, "utf8"); }
+    catch { continue; } // A thread can disappear between readdir and read.
+    for (const child of children.trim().split(/\s+/)) {
+      if (!child) continue;
+      const pid = Number(child);
+      let stat: string;
+      try { stat = readFileSync(`/proc/${pid}/stat`, "utf8"); }
+      catch { continue; } // The child may have exited and been reaped already.
+      // comm is parenthesized and may itself contain spaces or closing parens.
+      const fields = stat.slice(stat.lastIndexOf(")") + 2).trim().split(/\s+/);
+      if (fields[0] === "Z" && Number(fields[1]) === process.pid) {
+        zombies.set(pid, fields[19] ?? ""); // starttime distinguishes PID reuse.
+      }
+    }
+  }
+  return zombies;
+}
+
+// Dedicated systemd sessions already own descendant teardown via KillMode=control-group.
+// Let their manager promptly reap orphans (#2858); only unsupervised runners need
+// to adopt them here. Darwin has no process-local equivalent; launchd remains the reaper.
+export function enableRunnerSubreaper(): boolean {
+  if (process.platform !== "linux") return false;
+  try {
+    if (hasSystemdSessionOwner(readFileSync("/proc/self/cgroup", "utf8"), readFileSync(`/proc/${process.ppid}/comm`, "utf8"))) return false;
+  } catch { /* Unknown ownership keeps the fallback reaper. */ }
+  try {
+    const mappedLibc = readFileSync("/proc/self/maps", "utf8")
+      .split("\n")
+      .map((line) => line.match(/\s(\/\S*(?:libc\.so(?:\.\d+)*|ld-musl-\S+\.so\.1))$/)?.[1])
+      .find((path) => path && existsSync(path));
+    const libc = mappedLibc ?? [
+      "/lib/x86_64-linux-gnu/libc.so.6",
+      "/lib/aarch64-linux-gnu/libc.so.6",
+      "/lib64/libc.so.6",
+      "/usr/lib/libc.so.6",
+    ].find(existsSync);
+    if (!libc) {
+      console.error("[runner] cannot enable child subreaper: libc was not found");
+      return false;
+    }
+
+    const library = dlopen(libc, {
+      prctl: { args: ["int", "int", "int", "int", "int"], returns: "int" },
+      waitpid: { args: ["int", "ptr", "int"], returns: "int" },
+    });
+    // PR_SET_CHILD_SUBREAPER = 36 (linux/prctl.h). Children do not inherit the flag
+    // across fork/clone; execve preserves it for this process.
+    if (library.symbols.prctl(36, 1, 0, 0, 0) !== 0) {
+      library.close();
+      console.error("[runner] prctl(PR_SET_CHILD_SUBREAPER) failed");
+      return false;
+    }
+
+    if (!reaperStarted) {
+      reaperStarted = true;
+      const firstSeen = new Map<number, { starttime: string; at: number }>();
+      const timer = setInterval(() => {
+        try {
+          const now = Date.now();
+          const zombies = zombieChildren();
+          for (const [pid, starttime] of zombies) {
+            const seen = firstSeen.get(pid);
+            if (!seen || seen.starttime !== starttime) {
+              firstSeen.set(pid, { starttime, at: now });
+              continue;
+            }
+            if (now - seen.at >= ZOMBIE_GRACE_MS) {
+              // WNOHANG = 1. Never waitpid(-1): Bun owns its spawned children's
+              // exit statuses and must be allowed to collect them itself.
+              library.symbols.waitpid(pid, null, 1);
+              firstSeen.delete(pid);
+            }
+          }
+          for (const pid of firstSeen.keys()) {
+            if (!zombies.has(pid)) firstSeen.delete(pid);
+          }
+        } catch (error) {
+          console.error(`[runner] child reaper scan failed: ${error}`);
+        }
+      }, REAP_INTERVAL_MS);
+      timer.unref();
+    } else {
+      library.close();
+    }
+    return true;
+  } catch (error) {
+    console.error(`[runner] cannot enable child subreaper: ${error}`);
+    return false;
+  }
+}

package/src/template-resolver.ts

@@ -0,0 +1,29 @@
+import type { HumwickHttpClient } from "@humwick/sdk";
+import { RUNNER_PROMPT_TEMPLATE_DEFAULTS } from "@humwick/sdk/prompt-template-defaults";
+
+const RUNNER_DEFAULTS = new Map<string, string>(RUNNER_PROMPT_TEMPLATE_DEFAULTS.map((template) => [template.slug, template.defaultTemplate]));
+const templateCache = new Map<string, string>();
+
+function renderValue(value: string | undefined): string {
+  return value ?? "";
+}
+
+function applyVariables(template: string, vars: Record<string, string>): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key: string) => renderValue(vars[key]));
+}
+
+export async function initializeRunnerTemplates(http: HumwickHttpClient): Promise<void> {
+  try {
+    const templates = await http.listPromptTemplates();
+    templateCache.clear();
+    for (const template of templates) templateCache.set(template.slug, template.template);
+  } catch {
+    templateCache.clear();
+  }
+}
+
+export function renderRunnerTemplate(slug: string, vars: Record<string, string> = {}): string {
+  const template = templateCache.get(slug) ?? RUNNER_DEFAULTS.get(slug);
+  if (template === undefined) throw new Error(`unknown runner prompt template slug: ${slug}`);
+  return applyVariables(template, vars);
+}