@zgeoff/atc 3.1.1 → 3.3.0

package/src/daemon/local-pty-provider.ts

@@ -10,6 +10,7 @@ import type {
   HarnessHandle,
   HarnessSpec,
 } from './execution-provider';
+import { readNativeEnvKeys } from './read-native-env-keys';
 
 /**
  * The `local-pty` provider: harnesses run as child processes of the daemon
@@ -51,13 +52,21 @@ export class LocalPTYProvider implements ExecutionProvider {
       );
     }
 
-    const pty = spawn(spec.bin, [...spec.args], {
-      name: 'xterm-256color',
-      cols: spec.cols,
-      rows: spec.rows,
-      cwd: spec.cwd,
-      env: buildPTYEnv(spec),
-    });
+    const env = buildPTYEnv(spec);
+    const bin = resolveHarnessBin(spec.bin, env, spec.cwd);
+    const unset = buildUnsetNames(env, [...readNativeEnvKeys(), ...Object.keys(process.env)]);
+
+    const pty = spawn(
+      ENV_BIN,
+      buildEnvArgs(unset, buildDYLDEntries(env, process.platform), bin, spec.args),
+      {
+        name: 'xterm-256color',
+        cols: spec.cols,
+        rows: spec.rows,
+        cwd: spec.cwd,
+        env,
+      },
+    );
 
     const subscriptions = new Set<{ readonly dispose: () => void }>();
 
@@ -185,9 +194,7 @@ const USABLE_TERM = 'xterm-256color';
 
 // A pseudo-terminal always has a terminal on its far side, so a harness never
 // starts with an empty or dumb TERM, which leaves an agent CLI drawing with no
-// colour. TERM is always passed: the child starts from the environment the
-// daemon itself started with, and the keys passed here only add to it or
-// override it, so leaving TERM out hands the child the daemon's own value.
+// colour.
 function buildPTYEnv(spec: HarnessSpec): Record<string, string> {
   const env = collectCleanEnv(spec.env, spec.withheldEnv);
   const term = env['TERM'];
@@ -198,6 +205,72 @@ function buildPTYEnv(spec: HarnessSpec): Record<string, string> {
   };
 }
 
+// The PTY library starts its child from the environment the daemon started
+// with and lays the map over it, so the harness starts behind `env`, which
+// unsets every name the map leaves out before it replaces itself with the
+// harness. The pid stays the harness's own.
+const ENV_BIN = '/usr/bin/env';
+
+// The program is found on the map's PATH before the harness starts, so a
+// missing program fails the spawn as the PTY library fails it, instead of
+// starting `env` only to exit.
+function resolveHarnessBin(
+  bin: string,
+  env: Readonly<Record<string, string>>,
+  cwd: string,
+): string {
+  const resolved = Bun.which(bin, { PATH: env['PATH'] ?? '', cwd });
+
+  if (resolved === null) {
+    throw new Error(`PTY spawn failed: ${bin} is not a program the harness can start`);
+  }
+
+  return resolved;
+}
+
+// A name the native environment block cannot hold, such as one with `=`,
+// is left alone, since `env` refuses to unset it.
+function buildUnsetNames(
+  env: Readonly<Record<string, string>>,
+  inherited: readonly string[],
+): string[] {
+  return [...new Set(inherited)].filter(
+    (name) => name !== '' && !name.includes('=') && !Object.hasOwn(env, name),
+  );
+}
+
+// macOS clears every `DYLD_` variable on the way into `env`, a protected
+// system program, so the map's own ones are set again after the unsets, the
+// one place the argv holds a value.
+function buildDYLDEntries(
+  env: Readonly<Record<string, string>>,
+  platform: NodeJS.Platform,
+): string[] {
+  if (platform !== 'darwin') {
+    return [];
+  }
+
+  return Object.entries(env)
+    .filter(([name]) => name.startsWith('DYLD_'))
+    .map(([name, value]) => `${name}=${value}`);
+}
+
+// `env` reads a word holding `=` as an assignment even after `--`, so a
+// program path holding one starts through a shell that runs it by its first
+// argument.
+const SHELL_EXEC = 'exec "$0" "$@"';
+
+function buildEnvArgs(
+  unset: readonly string[],
+  entries: readonly string[],
+  bin: string,
+  args: readonly string[],
+): string[] {
+  const program = bin.includes('=') ? ['/bin/sh', '-c', SHELL_EXEC, bin] : [bin];
+
+  return [...unset.flatMap((name) => ['-u', name]), '--', ...entries, ...program, ...args];
+}
+
 // A process another user owns still runs, so only a missing process counts
 // as gone.
 function isProcessRunning(pid: number): boolean {

package/src/daemon/read-native-env-keys.ts

@@ -0,0 +1,74 @@
+import { CString, FFIType, dlopen, read } from 'bun:ffi';
+import { readFileSync } from 'node:fs';
+
+/**
+ * The names in the daemon process's native environment: the block a
+ * native library reads when it starts a child, as opposed to the copy Bun
+ * keeps for `process.env`. Changes to `process.env` never reach that
+ * block, so it keeps every variable the daemon started with, including
+ * ones deleted from `process.env` since.
+ *
+ * Linux reads the block from `/proc/self/environ`; macOS walks the live
+ * `environ` array that `_NSGetEnviron` returns. Any other platform throws,
+ * since a harness started without the list could inherit a withheld
+ * variable.
+ */
+export function readNativeEnvKeys(): string[] {
+  const keys = new Set<string>();
+
+  for (const entry of readNativeEnvEntries()) {
+    const eq = entry.indexOf('=');
+
+    if (eq > 0) {
+      keys.add(entry.slice(0, eq));
+    }
+  }
+
+  return [...keys];
+}
+
+function readNativeEnvEntries(): string[] {
+  if (process.platform === 'linux') {
+    return readFileSync('/proc/self/environ', 'utf8').split('\0');
+  }
+
+  if (process.platform === 'darwin') {
+    return readDarwinEnviron();
+  }
+
+  throw new Error(`atc cannot read the native environment on ${process.platform}`);
+}
+
+const POINTER_BYTES = 8;
+
+// `_NSGetEnviron` returns a pointer to `environ`, a NULL-terminated array of
+// `NAME=value` C strings.
+function readDarwinEnviron(): string[] {
+  const libSystem = dlopen('/usr/lib/libSystem.B.dylib', {
+    _NSGetEnviron: { args: [], returns: FFIType.ptr },
+  });
+
+  try {
+    // oxlint-disable-next-line no-underscore-dangle -- the libSystem symbol carries the underscore
+    const environ = libSystem.symbols._NSGetEnviron();
+
+    if (environ === null) {
+      throw new Error('atc cannot read the native environment: _NSGetEnviron returned NULL');
+    }
+
+    const array = read.ptr(environ);
+    const entries: string[] = [];
+
+    for (let offset = 0; ; offset += POINTER_BYTES) {
+      const entry = read.ptr(array, offset);
+
+      if (entry === 0) {
+        return entries;
+      }
+
+      entries.push(new CString(entry));
+    }
+  } finally {
+    libSystem.close();
+  }
+}

package/src/daemon-process.ts

@@ -0,0 +1,12 @@
+import type { DaemonFlags } from './parse-daemon-flags';
+
+// What a daemon was started with.
+export interface DaemonProcess {
+  readonly env: Readonly<Record<string, string>>;
+  readonly cwd: string | null;
+  readonly flags: DaemonFlags;
+
+  // False when `/proc` could not be read, in which case `env` is this
+  // process's own.
+  readonly fromProc: boolean;
+}

package/src/find-restart-unit.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseSystemdUnit } from './parse-systemd-unit';
+import { runSystemctl } from './run-systemctl';
+
+/**
+ * The user service whose main process is the daemon with this pid, or null
+ * when the daemon is not one.
+ *
+ * Two facts must hold. The daemon's cgroup sits in a `<name>.service` below
+ * the user manager, and the manager reports that unit's `MainPID` as this
+ * pid. The cgroup alone proves nothing: every process started from a
+ * session inside the unit, such as a daemon a test starts, shares the
+ * unit's cgroup without being the process the unit runs. `ATC_PROC_ROOT`
+ * moves the cgroup read from `/proc` to another directory, so a test can
+ * place a daemon in a unit without a user manager.
+ */
+export async function findRestartUnit(pid: number): Promise<string | null> {
+  const uid = process.getuid?.();
+
+  if (uid === undefined) {
+    return null;
+  }
+
+  let cgroup: string;
+
+  try {
+    cgroup = readFileSync(
+      join(process.env['ATC_PROC_ROOT'] ?? '/proc', String(pid), 'cgroup'),
+      'utf8',
+    );
+  } catch {
+    return null;
+  }
+
+  const unit = parseSystemdUnit(cgroup, uid);
+
+  if (unit === null) {
+    return null;
+  }
+
+  const shown = await runSystemctl(['show', '-p', 'MainPID', '--value', unit]);
+
+  return shown.code === 0 && shown.stdout === String(pid) ? unit : null;
+}

package/src/format-restart-preflight.ts

@@ -0,0 +1,74 @@
+import { parseMismatchBuild } from './parse-mismatch-build';
+import type { RestartPlan } from './restart-plan';
+
+const INTERRUPTION_POLICY =
+  'Stopping the daemon ends every agent process it hosts. A session that is mid-turn loses that turn; the restore resumes each session from its transcript, and the interrupted turn does not continue.';
+
+/**
+ * Renders what a restart is about to do: the daemon it stops, the sessions
+ * that are mid-turn, the replacement it starts, and the interruption
+ * policy.
+ */
+export function formatRestartPreflight(plan: RestartPlan): string[] {
+  return [...formatTarget(plan), ...formatReplacement(plan), INTERRUPTION_POLICY];
+}
+
+function formatTarget(plan: RestartPlan): string[] {
+  const pid = plan.pid === null ? 'pid unknown' : `pid ${plan.pid}`;
+
+  if (plan.answer === null) {
+    return [
+      plan.pid === null
+        ? 'no daemon answers and no live pid is recorded; the restart only starts one and restores the fleet'
+        : `the daemon (${pid}) does not answer; the restart stops it, starts one, and restores the fleet`,
+    ];
+  }
+
+  if (plan.answer.kind === 'refused') {
+    const parsed = parseMismatchBuild(plan.answer.message);
+
+    return [
+      `daemon: ${pid} refused this build's handshake: ${plan.answer.message}`,
+      ...(parsed === null
+        ? []
+        : [`daemon build ${parsed.build} speaks protocol v${parsed.protocol}`]),
+      'The session states cannot be read across the protocol mismatch, so the sessions that are mid-turn are unknown.',
+    ];
+  }
+
+  return [
+    `daemon: ${pid}, build ${plan.answer.build}, protocol v${plan.answer.protocol}`,
+    ...formatSessions(plan),
+  ];
+}
+
+function formatSessions(plan: RestartPlan): string[] {
+  if (plan.sessions === null) {
+    return ['The session list could not be read, so the sessions that are mid-turn are unknown.'];
+  }
+
+  const running = plan.sessions.filter((session) => session.state === 'running');
+
+  if (running.length === 0) {
+    return ['no session is mid-turn'];
+  }
+
+  return [
+    `${running.length} session${running.length === 1 ? ' is' : 's are'} mid-turn:`,
+    ...running.map(
+      (session) =>
+        `  ${session.name} (${session.id})${session.id === plan.callerSession ? ' (this session)' : ''}`,
+    ),
+  ];
+}
+
+function formatReplacement(plan: RestartPlan): string[] {
+  if (plan.replacement.kind === 'unit') {
+    return [
+      `replacement: systemd unit ${plan.replacement.unit}${plan.replacement.execStart === null ? '' : `, ExecStart ${plan.replacement.execStart}`}`,
+      'The unit decides the build the replacement runs.',
+    ];
+  }
+
+  return [`replacement: build ${plan.replacement.build}, started with ${plan.replacement.command}`];
+}

package/src/format-restart-report.ts

@@ -0,0 +1,45 @@
+import type { RestartResult } from './parse-restart-result';
+
+/**
+ * Renders a finished restart as the lines the run prints: the daemon now
+ * serving, how much of the fleet came back, each row that did not, and the
+ * sessions the restart interrupted.
+ */
+export function formatRestartReport(result: RestartResult): string[] {
+  const lines: string[] = [];
+
+  if (result.error !== null) {
+    lines.push(`restart failed: ${result.error}`);
+  }
+
+  if (result.pid !== null) {
+    lines.push(`daemon pid ${result.pid}, build ${result.build ?? 'unknown'}`);
+  }
+
+  if (result.listenPort !== null) {
+    lines.push(`listening on port ${result.listenPort}`);
+  }
+
+  if (result.error === null) {
+    lines.push(`restored ${result.restored} of ${result.total}`);
+  }
+
+  for (const row of result.failed) {
+    lines.push(`failed: ${row.name} (${row.id}): ${row.reason}`);
+  }
+
+  if (result.interrupted.length > 0) {
+    lines.push(`interrupted ${result.interrupted.length} mid-turn:`);
+
+    for (const row of result.interrupted) {
+      lines.push(`  ${row.name} (${row.id})`);
+    }
+  }
+
+  const verdict =
+    result.code === 0 ? 'restart succeeded' : `restart failed with exit code ${result.code}`;
+
+  lines.push(verdict);
+
+  return lines;
+}

package/src/is-daemon-command-line.ts

@@ -0,0 +1,33 @@
+import { basename } from 'node:path';
+
+/**
+ * Whether a command line starts the atc daemon: the atc entry (the `atc`
+ * shim or a compiled `atc` binary as the program, or the CLI source file as
+ * the runtime's script) directly followed by the `daemon` subcommand, and
+ * then nothing, a flag, or `serve`. Any other program that merely passes a
+ * `daemon` argument is not the daemon.
+ */
+export function isDaemonCommandLine(args: readonly string[]): boolean {
+  const at = args.indexOf('daemon');
+
+  if (at !== 1 && at !== 2) {
+    return false;
+  }
+
+  const entry = args[at - 1] ?? '';
+  const next = args[at + 1];
+
+  return isATCEntry(entry, at) && (next === undefined || next === 'serve' || next.startsWith('--'));
+}
+
+// The program itself when it sits first, or the script a runtime loads when
+// it sits second.
+function isATCEntry(entry: string, at: number): boolean {
+  const name = basename(entry);
+
+  if (at === 1 && /^atc(?:-[a-z0-9]+)*$/.test(name)) {
+    return true;
+  }
+
+  return at === 2 && (entry.endsWith('/src/cli.ts') || entry.endsWith('/bin/atc'));
+}

package/src/is-daemon-process.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { join } from 'node:path';
+import { isDaemonCommandLine } from './is-daemon-command-line';
+
+/**
+ * Whether the process with this pid runs `atc daemon` on this state
+ * directory: its command line starts the daemon, and the home in its
+ * environment puts its state directory at `stateDir`. A daemon of another
+ * checkout or another test home is not this one. A pid that cannot be read
+ * is not verified, so it reads as false: a recorded pid may have been reused
+ * by an unrelated process since the daemon died.
+ */
+export function isDaemonProcess(pid: number, stateDir: string): boolean {
+  let cmdline: string;
+  let environ: string;
+
+  try {
+    cmdline = readFileSync(`/proc/${pid}/cmdline`, 'utf8');
+    environ = readFileSync(`/proc/${pid}/environ`, 'utf8');
+  } catch {
+    return false;
+  }
+
+  if (!isDaemonCommandLine(cmdline.split('\0').filter((arg) => arg !== ''))) {
+    return false;
+  }
+
+  const homeVar = environ.split('\0').find((entry) => entry.startsWith('HOME='));
+  const home = homeVar === undefined || homeVar === 'HOME=' ? userInfo().homedir : homeVar.slice(5);
+
+  return join(home, '.local', 'state', 'atc') === stateDir;
+}

package/src/mcp/require-daemon-features.ts

@@ -11,6 +11,7 @@ const FEATURE_USES: Readonly<Record<DaemonFeature, string>> = {
   'message.turn': "atc_message_get's turn and answeredWith",
   'message.wait': "atc_message_get's waitMs",
   'session.forget': 'atc_session_forget',
+  'session.forget.preconditions': "atc_session_forget's pinned and live checks in the daemon",
   'session.locator': "a session's locator",
   'session.submit': 'atc_session_input',
   'spawn.idempotency': "atc_session_spawn's idempotencyKey",

package/src/mcp/run-tool.ts

@@ -147,18 +147,26 @@ export function runTool(
       return { text: 'killed', structured: null };
     })
     .with('atc_session_forget', async () => {
-      await requireForgettable(caller, args['session'], args['stop'] === true);
+      const params = {
+        session: args['session'],
+        ...(typeof args['confirmToken'] === 'string' ? { confirmToken: args['confirmToken'] } : {}),
+      };
 
-      const ok = await caller.sendRequest(
-        'session.forget',
-        {
-          session: args['session'],
-          ...(typeof args['confirmToken'] === 'string'
-            ? { confirmToken: args['confirmToken'] }
-            : {}),
-        },
-        ['session.forget'],
-      );
+      const stops = args['stop'] === true;
+
+      const features = await caller.readFeatures();
+
+      if (features.has('session.forget.preconditions')) {
+        const ok = await trySendGuardedForget(caller, params, stops);
+
+        if (ok !== null) {
+          return buildObjectResult(ok);
+        }
+      }
+
+      await requireForgettable(caller, args['session'], stops);
+
+      const ok = await caller.sendRequest('session.forget', params, ['session.forget']);
 
       return buildObjectResult(ok);
     })
@@ -285,6 +293,55 @@ function buildObjectResult(value: unknown): ToolResult {
   };
 }
 
+// The refusals of a forget, worded for an MCP client.
+const SESSION_PINNED_REFUSAL =
+  'session_pinned: the session is pinned, or is a sub-session of a pinned session. Unpin it with atc_session_update before forgetting it.';
+
+const SESSION_LIVE_REFUSAL =
+  'session_live: the session is live. Pass stop: true to stop and forget it.';
+
+// The daemon checks pinned and live in the same step that forgets, so a pin
+// or revive that lands just before the forget still refuses it. Null when
+// the daemon a gateway routes the forget to lacks the checks; the caller
+// then checks the session itself. A refusal keeps the wording of the
+// caller's own check.
+async function trySendGuardedForget(
+  caller: FleetCaller,
+  params: Readonly<Record<string, unknown>>,
+  stops: boolean,
+): Promise<Readonly<Record<string, unknown>> | null> {
+  try {
+    return await caller.sendRequest(
+      'session.forget',
+      { ...params, refusePinned: true, refuseLive: !stops },
+      ['session.forget', 'session.forget.preconditions'],
+    );
+  } catch (error) {
+    if (!(error instanceof Error) || !('code' in error)) {
+      throw error;
+    }
+
+    if (
+      error.code === 'daemon_outdated' &&
+      'data' in error &&
+      isRecord(error.data) &&
+      error.data['feature'] === 'session.forget.preconditions'
+    ) {
+      return null;
+    }
+
+    if (error.code === 'session_pinned') {
+      throw new Error(SESSION_PINNED_REFUSAL, { cause: error });
+    }
+
+    if (error.code === 'session_live') {
+      throw new Error(SESSION_LIVE_REFUSAL, { cause: error });
+    }
+
+    throw error;
+  }
+}
+
 // A forget is for good, so it reads the session first: an unseen or unknown
 // session fails here before the daemon mints a token, and a pinned or live
 // session is refused with the step that unblocks it.
@@ -306,13 +363,11 @@ async function requireForgettable(
   }
 
   if (pinned) {
-    throw new Error(
-      'session_pinned: the session is pinned, or is a sub-session of a pinned session. Unpin it with atc_session_update before forgetting it.',
-    );
+    throw new Error(SESSION_PINNED_REFUSAL);
   }
 
   if (descriptor['alive'] === true && !stops) {
-    throw new Error('session_live: the session is live. Pass stop: true to stop and forget it.');
+    throw new Error(SESSION_LIVE_REFUSAL);
   }
 }
 

package/src/parse-daemon-flags.ts

@@ -0,0 +1,33 @@
+export interface DaemonFlags {
+  readonly listen: string | null;
+  readonly tokenFile: string | null;
+}
+
+/**
+ * The `--listen` and `--token-file` values on a daemon's command line, read
+ * from the NUL-separated text of `/proc/<pid>/cmdline`. Both the
+ * `--flag value` and `--flag=value` forms count; a flag the line lacks reads
+ * as null.
+ */
+export function parseDaemonFlags(cmdline: string): DaemonFlags {
+  const args = cmdline.split('\0').filter((arg) => arg !== '');
+
+  return {
+    listen: findFlagValue(args, '--listen'),
+    tokenFile: findFlagValue(args, '--token-file'),
+  };
+}
+
+function findFlagValue(args: readonly string[], flag: string): string | null {
+  for (const [i, arg] of args.entries()) {
+    if (arg === flag) {
+      return args[i + 1] ?? null;
+    }
+
+    if (arg.startsWith(`${flag}=`)) {
+      return arg.slice(flag.length + 1);
+    }
+  }
+
+  return null;
+}

package/src/parse-mismatch-build.ts

@@ -0,0 +1,19 @@
+interface MismatchBuild {
+  readonly build: string;
+  readonly protocol: number;
+}
+
+/**
+ * The daemon's build and protocol version in its `protocol_mismatch`
+ * refusal text (`daemon <build> speaks v<N>`), or null when the text does
+ * not match that wording.
+ */
+export function parseMismatchBuild(text: string): MismatchBuild | null {
+  const match = /\bdaemon (?<build>\S+) speaks v(?<protocol>\d+)/.exec(text);
+
+  if (match === null) {
+    return null;
+  }
+
+  return { build: match.groups?.['build'] ?? '', protocol: Number(match.groups?.['protocol']) };
+}

package/src/parse-restart-result.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+
+export interface RestartFailedRow {
+  readonly name: string;
+  readonly id: string;
+  readonly reason: string;
+}
+
+interface RestartInterruptedRow {
+  readonly name: string;
+  readonly id: string;
+}
+
+/**
+ * What a finished restart reports: the daemon now serving, how much of the
+ * fleet came back, the rows that did not, and the sessions the restart
+ * interrupted. `code` is the exit code of the restart, and `error` holds the
+ * reason the restart stopped before it could count the fleet.
+ */
+export interface RestartResult {
+  readonly runID: string;
+  readonly code: number;
+  readonly pid: number | null;
+  readonly build: string | null;
+  readonly listenPort: number | null;
+  readonly restored: number;
+  readonly total: number;
+  readonly failed: readonly RestartFailedRow[];
+  readonly interrupted: readonly RestartInterruptedRow[];
+  readonly error: string | null;
+}
+
+const FAILED_ROW_SCHEMA = z.object({ name: z.string(), id: z.string(), reason: z.string() });
+const INTERRUPTED_ROW_SCHEMA = z.object({ name: z.string(), id: z.string() });
+
+const RESULT_SCHEMA = z.object({
+  runID: z.string(),
+  code: z.number().int(),
+  pid: z.number().int().nullable(),
+  build: z.string().nullable(),
+  listenPort: z.number().int().nullable(),
+  restored: z.number().int(),
+  total: z.number().int(),
+  failed: z.array(FAILED_ROW_SCHEMA),
+  interrupted: z.array(INTERRUPTED_ROW_SCHEMA),
+  error: z.string().nullable(),
+});
+
+/**
+ * Reads a restart result from a line of JSON, or null when the line holds
+ * anything else.
+ */
+export function parseRestartResult(line: string): RestartResult | null {
+  let raw: unknown;
+
+  try {
+    raw = JSON.parse(line);
+  } catch {
+    return null;
+  }
+
+  const parsed = RESULT_SCHEMA.safeParse(raw);
+
+  return parsed.success ? parsed.data : null;
+}