@zgeoff/atc 3.1.1 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

package/src/daemon/build-scoped-context.ts

@@ -137,8 +137,10 @@ export function buildScopedContext(
 
     // A session out of reach answers before any confirm token is handed
     // out or taken, so its host is never touched.
-    forgetSession: (id, confirmToken) =>
-      canSee(id) ? ctx.forgetSession(id, confirmToken) : Promise.resolve('missing' as const),
+    forgetSession: (id, confirmToken, refuse) =>
+      canSee(id)
+        ? ctx.forgetSession(id, confirmToken, refuse)
+        : Promise.resolve('missing' as const),
     revokeSessionAuth: (id) => (canSee(id) ? ctx.revokeSessionAuth(id) : Promise.resolve(false)),
     updateSessionAuth: (id) => (canSee(id) ? ctx.updateSessionAuth(id) : Promise.resolve(null)),
     updateSession: (id, name, pinned) => canSee(id) && ctx.updateSession(id, name, pinned),

package/src/daemon/daemon-connection.ts

@@ -650,7 +650,10 @@ export class DaemonConnection {
 
         const id = parsed.data.session;
 
-        const forgotten = await ctx.forgetSession(id, parsed.data.confirmToken);
+        const forgotten = await ctx.forgetSession(id, parsed.data.confirmToken, {
+          pinned: parsed.data.refusePinned === true,
+          live: parsed.data.refuseLive === true,
+        });
 
         if (forgotten === 'missing') {
           this.sendErr(req.id, 'no_such_session', `no session '${id}'`);

package/src/daemon/daemon-context.ts

@@ -63,6 +63,15 @@ type ForgetResult =
   | { readonly confirmToken: string; readonly expiresAt: number }
   | { readonly forgotten: true; readonly destroyed: boolean };
 
+/**
+ * The states a forget refuses to act on: a pinned session, or a sub-session
+ * of a pinned one, and a live session.
+ */
+interface ForgetRefusals {
+  readonly pinned: boolean;
+  readonly live: boolean;
+}
+
 // A transcript page with the file it came from, so a cursor into a replaced
 // transcript is distinguishable from one into a grown transcript.
 interface SessionTranscriptRead {
@@ -223,10 +232,12 @@ export interface DaemonContext {
   readonly killSession: (id: SessionID) => Promise<boolean>;
 
   // Forgets a session, or answers with the token a forget that destroys a
-  // host must carry. Throws the refusal for a token it does not take.
+  // host must carry. Throws the refusal for a token it does not take, and
+  // for a pinned or live session when the caller asks it to refuse one.
   readonly forgetSession: (
     id: SessionID,
     confirmToken: string | undefined,
+    refuse: ForgetRefusals,
   ) => Promise<ForgetResult | 'missing'>;
 
   // Withdraws the grants of the runtime auth binding on a session's host,

package/src/daemon/daemon.ts

@@ -1573,13 +1573,31 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     // A forget on a target that cannot destroy its host forgets at once. On
     // one that can, a forget without a token checks the target and answers
     // with a token, and the forget that carries the token destroys the host.
-    forgetSession: async (id, confirmToken) => {
+    // A refusal the caller asks for reads the session in the same step that
+    // starts the forget, so a pin or revive that lands first is seen.
+    forgetSession: async (id, confirmToken, refuse) => {
       const s = mgr.sessions.find((x) => x.id === id);
 
       if (s === undefined) {
         return 'missing';
       }
 
+      if (refuse.pinned && (s.pinned || mgr.sessions.some((x) => x.id === s.parent && x.pinned))) {
+        throw new DaemonError(
+          'session_pinned',
+          `session ${id} is pinned, or is a sub-session of a pinned session; unpin it before forgetting it`,
+          { session: id },
+        );
+      }
+
+      if (refuse.live && (s.pty !== null || (s.kind === 'headless' && s.state !== 'exited'))) {
+        throw new DaemonError(
+          'session_live',
+          `session ${id} is live; stop it before forgetting it`,
+          { session: id },
+        );
+      }
+
       if (mgr.findProvider(s)?.capabilities.destroy === true) {
         mgr.requireExecution(s, 'destroy');
 

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/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/protocol/daemon-features.ts

@@ -59,6 +59,11 @@ export const DAEMON_FEATURES = [
   // can destroy its host answers `confirmation_required`.
   'session.forget',
 
+  // `session.forget` takes `refusePinned` and `refuseLive`, checked in the
+  // same step that forgets, and refuses with `session_pinned` or
+  // `session_live`.
+  'session.forget.preconditions',
+
   // `session.submit` exists.
   'session.submit',
 

package/src/protocol/protocol.ts

@@ -71,6 +71,8 @@ const ERROR_CODES = [
   'host_leased',
   'confirmation_required',
   'confirm_token_invalid',
+  'session_pinned',
+  'session_live',
   'already_answered',
   'too_slow',
   'stale_epoch',

package/src/protocol/request-param-schemas.ts

@@ -213,6 +213,12 @@ export const REQUEST_PARAM_SCHEMAS = {
       .string({ error: 'session.forget confirmToken must be a string' })
       .min(1, 'session.forget confirmToken must not be empty')
       .optional(),
+
+    // Refuse a pinned session, or a sub-session of a pinned one.
+    refusePinned: z.boolean({ error: 'session.forget refusePinned must be a boolean' }).optional(),
+
+    // Refuse a live session.
+    refuseLive: z.boolean({ error: 'session.forget refuseLive must be a boolean' }).optional(),
   }),
 
   // Owner-only: withdraw the grants of the runtime auth binding on the