@outerlayer/cli 0.5.1 → 0.6.0

package/dist/{chunk-UWH5DSUP.js → chunk-VMJ3MMBX.js}

@@ -1,27 +1,29 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
+import { writeJobFile, readJobFile } from './chunk-T6OIJQRT.js';
+import { senderPidfile } from './chunk-ZILGTTY6.js';
 import { DOCKERD_LOG } from './chunk-CBPPJSAR.js';
-import { installScrubContext } from './chunk-ZOC7JSYC.js';
-import { AssetError, describeCallFailure, obtainImage, ensureRootfs, gitRemoteFor, startServicesFor, createBuildDisk, machineConfig, refusalCode, resolveAgentUser, AgentUserError, runBuildSteps, removeStagedContext, stageGovernedContext, shellQuote, ADDED_USER, createRunnerLog, createContainerRuntime, stopContainer, syncInContainer, formatDuration, cleanupContainer, retrySend, formatClock, GH_CONFIG_YML, ghHostsYml, isLiteralAddress, deleteBuildDisk } from './chunk-T52PKE2Y.js';
+import { installScrubContext } from './chunk-UMFWVGJO.js';
+import { AssetError, describeCallFailure, obtainImage, ensureRootfs, gitRemoteFor, startServicesFor, createBuildDisk, machineConfig, refusalCode, resolveAgentUser, AgentUserError, runBuildSteps, removeStagedContext, stageGovernedContext, shellQuote, createRunnerLog, createContainerRuntime, stopContainer, syncInContainer, formatDuration, cleanupContainer, retrySend, formatClock, containerSenderCommand, GH_CONFIG_YML, ghHostsYml, ADDED_USER, isLiteralAddress, signalInContainer, deleteBuildDisk, senderSignalScript } from './chunk-RZSF5B46.js';
 import { CLAUDE_CODE_VERSION } from './chunk-Z62HNKEJ.js';
 import { isSameProcess, startTimeOf } from './chunk-N5FOE5PS.js';
 import { childEnvironment } from './chunk-774HEQL6.js';
 import { waitForAgent, vmExecArgs } from './chunk-W4SQCOZU.js';
 import { socketPathProblem, vsockLinks, linkVsockSockets } from './chunk-B2G7JHHB.js';
-import { WorkCommandError, postJson, isSignatureRefusal, getJson } from './chunk-RMAZ2NWA.js';
-import { planArtifactUpload } from './chunk-WOBNRVQT.js';
-import { scrubText } from './chunk-EX6M5JPR.js';
+import { WorkCommandError, postJson, isSignatureRefusal, getJson } from './chunk-BNMCXPG7.js';
+import { planArtifactUpload } from './chunk-3DEVYTNQ.js';
+import { scrubText } from './chunk-ANK2B36Y.js';
 import { isBuiltinContainer, isBuiltinProcess, isBuiltinVm } from './chunk-3DD6AOWC.js';
 import { parseSize } from './chunk-F6GFZXZ3.js';
 import { claudeCredential, buildEnvironment, JOB_MOUNT, CHECKOUT_DIR, parseIsolation, proxyEnvironment, containerLocalAddress, destinationEnvironment, CLAUDE_CREDENTIAL_VARIABLES, builtInEnvironment, withHooksPath, startBuildServices, BUILT_IN_NAMES, AGENT_CREDENTIAL_MISSING, sharedUserEnvironment, headerVariables, authorEnvironment, withTunnelRecord, commitIdentityRecord, RELAY_PORT } from './chunk-AUFG23AA.js';
 import { readCloudConfig } from './chunk-EABW6AJQ.js';
 import { resolveVersion } from './chunk-RA3O54FC.js';
 import { signerFor } from './chunk-M5POMKKW.js';
-import { runnerDir, buildDir, vsockPath, RUNNER_DIR_MODE, RUNNER_FILE_MODE } from './chunk-ZM2IMMYN.js';
+import { runnerDir, buildDir, vsockPath, RUNNER_FILE_MODE } from './chunk-ZM2IMMYN.js';
 import { homeFromEnv } from './chunk-VNVZDWO3.js';
 import { spawn, spawnSync } from 'child_process';
 import { randomBytes } from 'crypto';
-import { mkdirSync, chmodSync, writeFileSync, appendFileSync, statSync, accessSync, constants, existsSync, readFileSync, openSync, closeSync, rmSync, readdirSync } from 'fs';
+import { mkdirSync, chmodSync, writeFileSync, appendFileSync, statSync, accessSync, constants, openSync, existsSync, readFileSync, closeSync, rmSync, readdirSync } from 'fs';
 import { join, isAbsolute, dirname, delimiter } from 'path';
 
 createRequire(import.meta.url);
@@ -192,9 +194,15 @@ async function provisionMicroVm(input) {
     return bail(`the build's disk and machine could not be made: ${describeCallFailure(err)}`);
   }
   if (input.aborted()) return bail("", true);
+  try {
+    state.cgroup = vm.cgroup.create(buildId, limits.memoryBytes);
+  } catch (err) {
+    return bail(`the build's memory limit could not be set: ${describeCallFailure(err)}`);
+  }
+  if (state.cgroup !== void 0) input.save(state, environment);
   const consolePath = join(jobDir, "vm-console.log");
   try {
-    state.firecracker = await vm.firecracker.spawn({ binary: assets.firecracker, configPath, consolePath });
+    state.firecracker = await vm.firecracker.spawn({ binary: assets.firecracker, configPath, consolePath, cgroup: state.cgroup });
   } catch (err) {
     return bail(`Firecracker did not start: ${describeCallFailure(err)}`);
   }
@@ -315,7 +323,7 @@ function agentVersionOf(toolsJson) {
   }
   return CLAUDE_CODE_VERSION;
 }
-function microVmCommandLine(input) {
+function vmExecFor(input, argv) {
   const state = input.job.microvm;
   const env = buildEnvironment({
     config: input.config,
@@ -334,13 +342,17 @@ function microVmCommandLine(input) {
     cwd: CHECKOUT_DIR,
     env: { ...state.imageEnv, ...env.literals },
     pass: Object.keys(env.passed).filter((name) => env.passed[name] !== void 0),
-    argv: ["/bin/sh", "-c", input.cmdline]
-  };
-  return {
-    line: [process.execPath, input.cli, "vm-exec", ...vmExecArgs(options)].map(shellQuote).join(" "),
-    options,
-    env: { ...childEnvironment(input.runtime.hostEnv), ...env.passed }
+    argv
   };
+  return { options, env: { ...childEnvironment(input.runtime.hostEnv), ...env.passed } };
+}
+function microVmCommandLine(input) {
+  const { options, env } = vmExecFor(input, ["/bin/sh", "-c", input.cmdline]);
+  return { line: [process.execPath, input.cli, "vm-exec", ...vmExecArgs(options)].map(shellQuote).join(" "), options, env };
+}
+function microVmSenderCommand(input) {
+  const { options, env } = vmExecFor(input, ["outerlayer", "session-sender"]);
+  return { command: process.execPath, args: [input.cli, "vm-exec", ...vmExecArgs(options)], env };
 }
 function isRunning(runtime, state) {
   return state.firecracker !== void 0 && runtime.vm.firecracker.alive(state.firecracker);
@@ -391,6 +403,13 @@ async function cleanupMicroVm(runtime, state, jobDir) {
       failures.push(`the microVM (pid ${state.firecracker.pid}) was not stopped: ${describeCallFailure(err)}`);
     }
   }
+  if (state.cgroup !== void 0) {
+    try {
+      runtime.vm.cgroup.remove(state.cgroup);
+    } catch (err) {
+      failures.push(`the build's cgroup ${state.cgroup} was not removed: ${describeCallFailure(err)}`);
+    }
+  }
   if (state.buildDisk !== void 0) deleteBuildDisk(state.buildDisk);
   const tunnel = runtime.tunnels.get(state.buildId);
   if (tunnel !== void 0) {
@@ -583,70 +602,6 @@ async function closeHostBuild(runtime, build) {
   rmSync(build.buildDir, { recursive: true, force: true });
   if (build.workDir !== void 0) rmSync(build.workDir, { recursive: true, force: true });
 }
-var ENDED = "ended before provision finished";
-async function provisionProcess(input) {
-  const { config, runtime, item, jobDir } = input;
-  if (claudeCredential(runtime.hostEnv) === void 0) return { ok: false, reason: AGENT_CREDENTIAL_MISSING };
-  const repository = item.specRepository;
-  if (repository === void 0 || repository === null || repository === "") {
-    return { ok: false, reason: "the work item names no repository to clone" };
-  }
-  const buildId = randomBytes(6).toString("hex");
-  const buildDir2 = buildDir(config.configPath, buildId);
-  const workDir = join(jobDir, "work");
-  const state = { buildId, buildDir: buildDir2, workDir };
-  const environment = sharedUserEnvironment(input.cliVersion);
-  input.save(state, environment);
-  const bail = async (reason) => {
-    try {
-      await cleanupProcess(runtime, state);
-    } catch (err) {
-      input.log.error(`#${item.number} cleanup failed: ${describeCallFailure(err)}`);
-    }
-    return { ok: false, reason };
-  };
-  if (input.aborted()) return bail(ENDED);
-  mkdirSync(buildDir2, { recursive: true });
-  chmodSync(buildDir2, 493);
-  try {
-    await startHostServices({ runtime, config, build: state, jobDir, itemKey: input.itemKey, process: true });
-  } catch (err) {
-    return bail(`the tunnel could not start: ${describeCallFailure(err)}`);
-  }
-  input.save(state, environment);
-  if (input.aborted()) return bail(ENDED);
-  const checkout = join(workDir, "checkout");
-  const remote = runtime.remoteFor?.(repository) ?? `https://github.com/${repository}.git`;
-  const cloned = await runtime.clone({ remote, dest: checkout });
-  if (!cloned.ok) return bail(cloned.reason);
-  if (input.aborted()) return bail(ENDED);
-  return { ok: true, workdir: checkout, state, environment };
-}
-function cleanupProcess(runtime, state) {
-  return closeHostBuild(runtime, state);
-}
-function readJobFile(path) {
-  if (!existsSync(path)) return null;
-  try {
-    return JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    return null;
-  }
-}
-function readJobFileChecked(path) {
-  if (!existsSync(path)) return { kind: "missing" };
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return { kind: "unreadable" };
-    return { kind: "ok", job: parsed };
-  } catch {
-    return { kind: "unreadable" };
-  }
-}
-function writeJobFile(path, job) {
-  mkdirSync(dirname(path), { recursive: true, mode: RUNNER_DIR_MODE });
-  writeFileSync(path, JSON.stringify(job, null, 2), { mode: RUNNER_FILE_MODE });
-}
 
 // src/runner/verdict.ts
 var VERDICT_SETTLE_MS = 5 * 6e4;
@@ -720,6 +675,48 @@ async function settleVerdict(deps) {
     await deps.sleep(everyMs);
   }
 }
+var ENDED = "ended before provision finished";
+async function provisionProcess(input) {
+  const { config, runtime, item, jobDir } = input;
+  if (claudeCredential(runtime.hostEnv) === void 0) return { ok: false, reason: AGENT_CREDENTIAL_MISSING };
+  const repository = item.specRepository;
+  if (repository === void 0 || repository === null || repository === "") {
+    return { ok: false, reason: "the work item names no repository to clone" };
+  }
+  const buildId = randomBytes(6).toString("hex");
+  const buildDir2 = buildDir(config.configPath, buildId);
+  const workDir = join(jobDir, "work");
+  const state = { buildId, buildDir: buildDir2, workDir };
+  const environment = sharedUserEnvironment(input.cliVersion);
+  input.save(state, environment);
+  const bail = async (reason) => {
+    try {
+      await cleanupProcess(runtime, state);
+    } catch (err) {
+      input.log.error(`#${item.number} cleanup failed: ${describeCallFailure(err)}`);
+    }
+    return { ok: false, reason };
+  };
+  if (input.aborted()) return bail(ENDED);
+  mkdirSync(buildDir2, { recursive: true });
+  chmodSync(buildDir2, 493);
+  try {
+    await startHostServices({ runtime, config, build: state, jobDir, itemKey: input.itemKey, process: true });
+  } catch (err) {
+    return bail(`the tunnel could not start: ${describeCallFailure(err)}`);
+  }
+  input.save(state, environment);
+  if (input.aborted()) return bail(ENDED);
+  const checkout = join(workDir, "checkout");
+  const remote = runtime.remoteFor?.(repository) ?? `https://github.com/${repository}.git`;
+  const cloned = await runtime.clone({ remote, dest: checkout });
+  if (!cloned.ok) return bail(cloned.reason);
+  if (input.aborted()) return bail(ENDED);
+  return { ok: true, workdir: checkout, state, environment };
+}
+function cleanupProcess(runtime, state) {
+  return closeHostBuild(runtime, state);
+}
 
 // src/runner/job.ts
 var LEASE_SECONDS = 900;
@@ -1167,6 +1164,11 @@ async function finishJob(job, jobDirPath, outcome, config, deps, ending) {
   const jobFilePath = join(jobDirPath, "job.json");
   const logPath = join(jobDirPath, "command.log");
   const tag = `#${job.item}`;
+  if (job.sender !== void 0) {
+    await stopSender({ job, deps: { spawnFn, runtime: deps.container, log } });
+    delete job.sender;
+    writeJobFile(jobFilePath, job);
+  }
   const build = job.container === void 0 ? void 0 : { state: job.container, runtime: deps.container ?? createContainerRuntime() };
   const vmBuild = job.microvm === void 0 ? void 0 : { state: job.microvm, runtime: deps.container ?? createContainerRuntime() };
   if (build !== void 0 && job.pid !== void 0 && isGroupAlive(job.pid)) {
@@ -1189,6 +1191,20 @@ async function finishJob(job, jobDirPath, outcome, config, deps, ending) {
     job.reason = scrubReason(ending.reason, config);
     writeJobFile(jobFilePath, job);
   }
+  let outOfMemory;
+  if (vmBuild?.state.cgroup !== void 0 && outcome !== void 0 && outcome !== "ok" && ending?.reason === void 0) {
+    try {
+      if (vmBuild.runtime.vm.cgroup.oomKills(vmBuild.state.cgroup) > 0) {
+        outOfMemory = `the build ran out of memory: the kernel killed its microVM at the limit of runner.build.memory (${config.build?.memory ?? "8g"}) plus 256 MiB for Firecracker. Raise runner.build.memory, or lower runner.concurrency`;
+      }
+    } catch (err) {
+      log.error(`${tag} could not read the build's memory events: ${describeCallFailure(err)} \xB7 continuing`);
+    }
+    if (outOfMemory !== void 0) {
+      job.reason = scrubReason(outOfMemory, config);
+      writeJobFile(jobFilePath, job);
+    }
+  }
   const hookLimits = () => hookLimitsFor(config, now().getTime(), deps.now);
   let tunnelRecord;
   if (!job.cleanupRan) {
@@ -1352,6 +1368,8 @@ async function finishJob(job, jobDirPath, outcome, config, deps, ending) {
     const fromHook = readReasonLine(jobDirPath, config);
     if (verdictReason !== void 0) {
       job.reason = verdictReason;
+    } else if (outOfMemory !== void 0) {
+      job.reason = scrubReason(outOfMemory, config);
     } else if (ending?.reason === void 0) {
       job.reason = (outcome === "ok" ? void 0 : held?.reason) ?? (isolated ? fromHook ?? job.reason : fromHook);
     }
@@ -1470,4 +1488,109 @@ async function recoverLostJobs(jobsDirPath, config, deps) {
   return recovered;
 }
 
-export { ALREADY_RELEASED, LEASE_SECONDS, RENEW_INTERVAL_SECONDS, deliverCommitHooks, describeHookEnd, execArgv, execCommandLine, finishJob, hookLimitsFor, hostCommandEnvironment, hostEnvironment, isGroupAlive, isIdle, isTimedOut, isUnfinished, jobEnv, listAdoptableJobs, listenOnBroker, microVmCommandLine, needsRenew, outcomeFromExitCode, provisionEnvironment, provisionMicroVm, provisionProcess, readCpuUsec, readJobFile, readJobFileChecked, readProvisionOut, recoverLostJobs, releaseLease, renewLease, resolveHostBuild, retryFailedReleases, runCommand, runHook, setStage, startHostServices, stopOrphanedMicroVms, unfinishedJobs, workdirProblem, writeJobFile };
+// src/runner/sender.ts
+var STOP_WAIT_MS = 3e4;
+var POLL_MS = 200;
+var BUILD_HOME = "/build/home";
+async function startSender(input) {
+  const { config, job, jobDir, deps } = input;
+  const tag = `#${job.item}`;
+  if (job.itemKey === void 0) return void 0;
+  const spawnFn = deps.spawnFn ?? spawn;
+  try {
+    const launch = launchFor(config, job, jobDir, deps);
+    const fd = openSync(join(jobDir, "sender.log"), "a", RUNNER_FILE_MODE);
+    let pid;
+    try {
+      const child = spawnFn(launch.command, launch.args, { env: launch.env, cwd: launch.cwd, detached: true, stdio: ["ignore", fd, fd] });
+      child.on("error", (err) => deps.log.error(`${tag} session sender failed: ${describeCallFailure(err)}`));
+      child.on("exit", (code, signal) => deps.log.line(`${tag} session sender exited \xB7 ${signal ?? `code ${code}`} \xB7 see sender.log`));
+      child.unref?.();
+      pid = child.pid;
+    } finally {
+      closeSync(fd);
+    }
+    if (pid === void 0) {
+      deps.log.line(`${tag} session sender did not start: no pid`);
+      return void 0;
+    }
+    deps.log.line(`${tag} session sender started \xB7 pid ${pid}`);
+    return { pid, start: startTimeOf(pid) ?? void 0 };
+  } catch (err) {
+    deps.log.error(`${tag} session sender did not start: ${describeCallFailure(err)} \xB7 continuing`);
+    return void 0;
+  }
+}
+function launchFor(config, job, jobDir, deps) {
+  if (job.microvm !== void 0) {
+    const runtime = deps.runtime ?? createContainerRuntime();
+    const cli = deps.cliPath ?? join(runtime.cliBuild().distDir, "index.js");
+    return { ...microVmSenderCommand({ job, runtime, config, cli }), cwd: jobDir };
+  }
+  if (job.container !== void 0) {
+    return { ...containerSenderCommand({ job, runtime: deps.runtime ?? createContainerRuntime(), config }), cwd: jobDir };
+  }
+  const env = jobEnv(config, job.item, job.itemKey, jobDir, process.env, job.branch, job.commitIdentity?.author);
+  const build = job.build;
+  const hostEnv = build === void 0 ? env : hostCommandEnvironment(env, build, config, job.commitIdentity?.hooksPath);
+  if (build?.exec !== void 0) {
+    return { command: build.exec, args: execArgv(job.workdir, ["outerlayer", "session-sender"]), env: hostEnv, cwd: jobDir };
+  }
+  return { command: process.execPath, args: [deps.cliPath ?? process.argv[1] ?? "outerlayer", "session-sender"], env: hostEnv, cwd: job.workdir ?? jobDir };
+}
+function isLive(sender) {
+  if (sender.start !== void 0) return isSameProcess(sender.pid, sender.start);
+  try {
+    process.kill(sender.pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function signalHost(sender, signal) {
+  if (!isLive(sender)) return;
+  try {
+    process.kill(-sender.pid, signal);
+  } catch {
+    try {
+      process.kill(sender.pid, signal);
+    } catch {
+    }
+  }
+}
+async function signalInGuest(runtime, state, pidfile, signal) {
+  await runtime.vm.exec(state.vsockPath, {
+    argv: ["/bin/sh", "-c", senderSignalScript(pidfile, signal)],
+    user: state.agentUser ?? ADDED_USER,
+    cwd: "/",
+    env: { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" }
+  });
+}
+async function stopSender(input) {
+  const { job, deps } = input;
+  const sender = job.sender;
+  if (sender === void 0) return;
+  const tag = `#${job.item}`;
+  const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const inContainer = job.container === void 0 ? void 0 : { state: job.container, runtime: deps.runtime ?? createContainerRuntime(), pidfile: senderPidfile(BUILD_HOME, Number(job.item)) };
+  const inGuest = job.microvm === void 0 ? void 0 : { state: job.microvm, runtime: deps.runtime ?? createContainerRuntime(), pidfile: senderPidfile(BUILD_HOME, Number(job.item)) };
+  const signalInside = async (signal) => {
+    if (inContainer !== void 0) await signalInContainer(inContainer.runtime, inContainer.state, inContainer.pidfile, signal).catch(() => void 0);
+    if (inGuest !== void 0) await signalInGuest(inGuest.runtime, inGuest.state, inGuest.pidfile, signal).catch(() => void 0);
+  };
+  try {
+    if (inContainer !== void 0 || inGuest !== void 0) await signalInside("TERM");
+    else signalHost(sender, "SIGTERM");
+    const deadline = (deps.waitMs ?? STOP_WAIT_MS) / POLL_MS;
+    for (let waited = 0; isLive(sender) && waited < deadline; waited += 1) await sleep(POLL_MS);
+    if (isLive(sender)) {
+      deps.log.error(`${tag} session sender did not stop in time \xB7 killing it`);
+      await signalInside("KILL");
+      signalHost(sender, "SIGKILL");
+    }
+  } catch (err) {
+    deps.log.error(`${tag} stopping the session sender failed: ${describeCallFailure(err)} \xB7 continuing`);
+  }
+}
+
+export { ALREADY_RELEASED, LEASE_SECONDS, RENEW_INTERVAL_SECONDS, deliverCommitHooks, describeHookEnd, execArgv, execCommandLine, finishJob, hookLimitsFor, hostCommandEnvironment, hostEnvironment, isGroupAlive, isIdle, isTimedOut, isUnfinished, jobEnv, listAdoptableJobs, listenOnBroker, microVmCommandLine, needsRenew, outcomeFromExitCode, provisionEnvironment, provisionMicroVm, provisionProcess, readCpuUsec, readProvisionOut, recoverLostJobs, releaseLease, renewLease, resolveHostBuild, retryFailedReleases, runCommand, runHook, setStage, startHostServices, startSender, stopOrphanedMicroVms, unfinishedJobs, workdirProblem };

package/dist/chunk-ZILGTTY6.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { LiveUploader } from './chunk-UMFWVGJO.js';
+import { CaptureDaemon } from './chunk-ANK2B36Y.js';
+import { parseWorkItemEnv } from './chunk-GQD22KKN.js';
+import { spoolDir } from './chunk-FA2BOX4O.js';
+import { homeFromEnv } from './chunk-VNVZDWO3.js';
+import { mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+
+createRequire(import.meta.url);
+var SENDER_STOP_WAIT_MS = 25e3;
+var RESCAN_MS = 3e4;
+function senderPidfile(home, item) {
+  return join(spoolDir(home), `session-sender-${item}.pid`);
+}
+async function startSessionSender(opts = {}) {
+  const env = opts.env ?? process.env;
+  const stderr = opts.stderr ?? ((s) => void process.stderr.write(s));
+  const parsed = parseWorkItemEnv(env.OUTERLAYER_WORK);
+  const jobDir = env.OUTERLAYER_JOB_DIR;
+  if ("reason" in parsed || !jobDir) {
+    throw new Error("a session sender runs inside a runner job: OUTERLAYER_WORK must name the item and OUTERLAYER_JOB_DIR the job");
+  }
+  const home = opts.home ?? homeFromEnv(env);
+  const uploader = new LiveUploader({
+    home,
+    env,
+    fetchImpl: opts.fetchImpl,
+    sleepImpl: opts.sleepImpl,
+    debounceMs: opts.debounceMs,
+    stderr,
+    build: { item: parsed.number, jobDir },
+    onUnauthorized: opts.onFatal
+  });
+  const onLog = (event) => {
+    if (event.type === "changed" && event.file !== void 0) uploader.notify(event.file);
+    if (event.type === "error") stderr(`error ${event.file}: ${event.detail}
+`);
+  };
+  const daemon = new CaptureDaemon({ ...opts.root === void 0 ? {} : { root: opts.root }, watchOnly: true, rescanMs: RESCAN_MS, onLog });
+  const pidfile = senderPidfile(home, parsed.number);
+  try {
+    mkdirSync(spoolDir(home), { recursive: true });
+    writeFileSync(pidfile, String(process.pid));
+  } catch {
+  }
+  await daemon.start();
+  let stopped;
+  return {
+    stop: () => stopped ??= (async () => {
+      daemon.rescanNow();
+      await uploader.stop(opts.stopWaitMs ?? SENDER_STOP_WAIT_MS);
+      await daemon.stop();
+      rmSync(pidfile, { force: true });
+    })()
+  };
+}
+async function runSessionSender() {
+  let sender;
+  const exit = async (code) => {
+    await sender?.stop().catch(() => void 0);
+    process.exit(code);
+  };
+  sender = await startSessionSender({ onFatal: () => void exit(1) });
+  process.on("SIGTERM", () => void exit(0));
+  process.on("SIGINT", () => void exit(0));
+  process.on("unhandledRejection", (reason) => {
+    process.stderr.write(`session-sender: unhandled error, continuing: ${String(reason)}
+`);
+  });
+  await new Promise(() => void 0);
+}
+
+export { runSessionSender, senderPidfile, startSessionSender };