@zgeoff/atc 2.12.0 → 2.13.0

package/src/run-bridge-tap.ts

@@ -0,0 +1,241 @@
+import { readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { openBridgeSocket } from './shared/open-bridge-socket';
+import type { BridgeSocket } from './shared/open-bridge-socket';
+
+const INBOX_MESSAGE_SCHEMA = z.looseObject({
+  ev: z.literal('InboxMessage'),
+  message: z.string(),
+  from: z.string(),
+  text: z.string(),
+  sentAt: z.number(),
+});
+
+const OUTBOX_REPORT_SCHEMA = z.object({
+  reportID: z.string().min(1),
+  payload: z.record(z.string(), z.unknown()),
+});
+
+// The wait before the first reconnect, doubling up to the longest.
+const FIRST_RETRY_MS = 250;
+const LONGEST_RETRY_MS = 5000;
+
+// How many message ids the tap remembers having printed.
+const SEEN_LIMIT = 10_000;
+
+// How one connection to the bridge ended: the inbox closed for good, the
+// bridge refused the tap, or the connection dropped after or before it
+// opened the tap.
+type TapEnd = 'closed' | 'refused' | 'lost' | 'unreachable';
+
+/**
+ * Streams the session's inbox to stdout from inside a remote host, through
+ * the session bridge at the given socket. It prints each message once as
+ * one NDJSON line and acks it after the line is written. A dropped
+ * connection, as a host's sleep or a daemon restart leaves it, reconnects
+ * with a growing wait of at most 5 seconds and no end; each new connection
+ * replays the messages not yet acked, and one already printed is acked
+ * again and not printed twice. Each connection also sends the reports the
+ * outbox still holds. Exits 0 once the inbox closes and 1 when the bridge
+ * refuses the tap.
+ */
+export async function runBridgeTap(socketPath: string, outbox: string): Promise<void> {
+  const seen = new Set<string>();
+
+  let wait = FIRST_RETRY_MS;
+
+  for (;;) {
+    const end = await runTapConnection(socketPath, outbox, seen);
+
+    if (end === 'closed') {
+      process.exit(0);
+    }
+
+    if (end === 'refused') {
+      console.error('atc tap: the session bridge refused the tap');
+      process.exit(1);
+    }
+
+    if (end === 'lost') {
+      wait = FIRST_RETRY_MS;
+    }
+
+    await Bun.sleep(wait);
+
+    wait = Math.min(wait * 2, LONGEST_RETRY_MS);
+  }
+}
+
+async function runTapConnection(
+  socketPath: string,
+  outbox: string,
+
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- the ids the tap printed, which every connection adds to
+  seen: Set<string>,
+): Promise<TapEnd> {
+  const ended = Promise.withResolvers<TapEnd>();
+  let opened = false;
+  let printing: Promise<void> = Promise.resolve();
+  let socket: BridgeSocket;
+
+  // The outbox file behind each report this connection sent, by request id.
+  let sent = new Map<string, string>();
+
+  const onLine = (line: Readonly<Record<string, unknown>>) => {
+    if (line['ev'] === 'InboxClosed') {
+      ended.resolve('closed');
+
+      return;
+    }
+
+    if (line['id'] === 'tap.open') {
+      if (line['ok'] !== true) {
+        ended.resolve('refused');
+
+        return;
+      }
+
+      opened = true;
+      sent = sendOutboxReports(socket, outbox);
+
+      return;
+    }
+
+    // A report the bridge took, or one it refuses outright, leaves the
+    // outbox: no resend would change the answer. Only the file this
+    // connection sent under the answered id is removed.
+    if (typeof line['id'] === 'string' && line['id'].startsWith('report:')) {
+      const path = sent.get(line['id']);
+
+      if (path !== undefined && (line['ok'] === true || line['code'] === 'forbidden')) {
+        sent.delete(line['id']);
+
+        rmSync(path, { force: true });
+      }
+
+      return;
+    }
+
+    if (line['ok'] === false && line['code'] === 'stale_binding') {
+      ended.resolve('refused');
+
+      return;
+    }
+
+    const msg = INBOX_MESSAGE_SCHEMA.safeParse(line);
+
+    if (!msg.success) {
+      return;
+    }
+
+    const message = msg.data;
+    const previous = printing;
+
+    printing = (async () => {
+      await previous;
+
+      if (!seen.has(message.message)) {
+        const printed = `${JSON.stringify({ id: message.message, from: message.from, text: message.text, sentAt: message.sentAt })}\n`;
+
+        try {
+          await Bun.write(Bun.stdout, printed);
+        } catch {
+          process.exit(1);
+        }
+
+        updateSeenIDs(seen, message.message);
+      }
+
+      socket.writeLine({
+        v: 1,
+        id: `ack:${message.message}`,
+        op: 'tap.ack',
+        message: message.message,
+      });
+    })();
+  };
+
+  try {
+    socket = await openBridgeSocket(socketPath, onLine);
+  } catch {
+    return 'unreachable';
+  }
+
+  void (async () => {
+    await socket.closed;
+
+    const end: TapEnd = opened ? 'lost' : 'unreachable';
+
+    ended.resolve(end);
+  })();
+
+  socket.writeLine({ v: 1, id: 'tap.open', op: 'tap.open' });
+
+  const end = await ended.promise;
+
+  await printing.catch(() => {});
+
+  socket.end();
+
+  return end;
+}
+
+// Sends every report the outbox holds, and returns the file behind each
+// request id it sent; a file that is no report is removed, since no answer
+// would ever clear it.
+// oxlint-disable-next-line prefer-readonly-parameter-types -- a socket is a live handle
+function sendOutboxReports(socket: BridgeSocket, outbox: string): Map<string, string> {
+  const sent = new Map<string, string>();
+
+  let files: string[];
+
+  try {
+    files = readdirSync(outbox).filter((file) => file.endsWith('.json'));
+  } catch {
+    return sent;
+  }
+
+  for (const file of files) {
+    const path = join(outbox, file);
+    let report: z.infer<typeof OUTBOX_REPORT_SCHEMA> | null = null;
+
+    try {
+      const parsed = OUTBOX_REPORT_SCHEMA.safeParse(JSON.parse(readFileSync(path, 'utf8')));
+
+      report = parsed.success ? parsed.data : null;
+    } catch {}
+
+    if (report === null) {
+      rmSync(path, { force: true });
+      continue;
+    }
+
+    const id = `report:${report.reportID}`;
+
+    sent.set(id, path);
+
+    socket.writeLine({
+      v: 1,
+      id,
+      op: 'report',
+      reportID: report.reportID,
+      payload: report.payload,
+    });
+  }
+
+  return sent;
+}
+
+// oxlint-disable-next-line prefer-readonly-parameter-types -- the set grows in place
+function updateSeenIDs(seen: Set<string>, id: string): void {
+  seen.add(id);
+
+  for (const oldest of seen) {
+    if (seen.size <= SEEN_LIMIT) {
+      break;
+    }
+
+    seen.delete(oldest);
+  }
+}

package/src/shared/collect-clean-env.ts

@@ -3,14 +3,22 @@
  * scrubbed out. A child that inherits those variables behaves as part of
  * the parent session — Claude transcripts nest, and Grok joins the
  * parent's in-process dashboard — which breaks resume and isolation.
+ *
+ * Variables named in `withheld` are left out of what the child inherits,
+ * such as a workspace credential that only the daemon's own git commands
+ * may see. The extras the caller sets explicitly are added after, so one
+ * of them is kept even when it shares a withheld name.
  */
 export function collectCleanEnv(
   extra: Readonly<Record<string, string>> = {},
+  withheld: readonly string[] = [],
 ): Record<string, string> {
   const env: Record<string, string> = {};
 
+  const skipped = new Set(withheld);
+
   for (const [key, value] of Object.entries(process.env)) {
-    if (value === undefined || isParentSessionKey(key)) {
+    if (value === undefined || isParentSessionKey(key) || skipped.has(key)) {
       continue;
     }
 

package/src/shared/open-bridge-socket.ts

@@ -0,0 +1,86 @@
+/**
+ * One line-framed connection to a session bridge, from inside a remote
+ * session: each line the bridge writes arrives whole, and each line written
+ * here goes out in order, across as many socket writes as it takes.
+ */
+export interface BridgeSocket {
+  readonly writeLine: (value: Readonly<Record<string, unknown>>) => void;
+  readonly end: () => void;
+
+  // Settles once the connection has closed, from either side.
+  readonly closed: Promise<void>;
+}
+
+/**
+ * Connects to the session bridge at a unix socket path. Rejects when
+ * nothing listens there.
+ */
+export async function openBridgeSocket(
+  path: string,
+  onLine: (line: Readonly<Record<string, unknown>>) => void,
+): Promise<BridgeSocket> {
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+
+  const closed = Promise.withResolvers<void>();
+  let pending = '';
+
+  let unsent = new Uint8Array(0);
+
+  const socket = await Bun.connect({
+    unix: path,
+    socket: {
+      data(_socket, buf) {
+        const lines = `${pending}${decoder.decode(buf, { stream: true })}`.split('\n');
+
+        pending = lines.pop() ?? '';
+
+        for (const line of lines) {
+          const parsed = parseLine(line);
+
+          if (parsed !== null) {
+            onLine(parsed);
+          }
+        }
+      },
+      drain(s) {
+        unsent = unsent.subarray(s.write(unsent));
+      },
+      close() {
+        closed.resolve();
+      },
+      error() {
+        closed.resolve();
+      },
+    },
+  });
+
+  return {
+    writeLine: (value) => {
+      const bytes = encoder.encode(`${JSON.stringify(value)}\n`);
+
+      const joined = new Uint8Array(unsent.length + bytes.length);
+
+      joined.set(unsent, 0);
+      joined.set(bytes, unsent.length);
+
+      unsent = joined.subarray(socket.write(joined));
+    },
+    end: () => {
+      socket.end();
+    },
+    closed: closed.promise,
+  };
+}
+
+function parseLine(line: string): Readonly<Record<string, unknown>> | null {
+  try {
+    const parsed: unknown = JSON.parse(line);
+
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+      ? Object.fromEntries(Object.entries(parsed))
+      : null;
+  } catch {
+    return null;
+  }
+}

package/src/shared/send-bridge-request.ts

@@ -0,0 +1,47 @@
+import { randomUUID } from 'node:crypto';
+import { openBridgeSocket } from './open-bridge-socket';
+
+/**
+ * Sends one request to the session bridge at a unix socket path and
+ * returns its answer line, or null when nothing listens there, the
+ * connection closes first, or no answer arrives in time. Never throws.
+ */
+export async function sendBridgeRequest(
+  path: string,
+  op: string,
+  args: Readonly<Record<string, unknown>>,
+  timeoutMs: number,
+): Promise<Readonly<Record<string, unknown>> | null> {
+  const id = randomUUID();
+  const answered = Promise.withResolvers<Readonly<Record<string, unknown>> | null>();
+
+  try {
+    const socket = await openBridgeSocket(path, (line) => {
+      if (line['id'] === id) {
+        answered.resolve(line);
+      }
+    });
+
+    void (async () => {
+      await socket.closed;
+
+      answered.resolve(null);
+    })();
+
+    const timer = setTimeout(() => {
+      answered.resolve(null);
+    }, timeoutMs);
+
+    socket.writeLine({ ...args, v: 1, id, op });
+
+    const answer = await answered.promise;
+
+    clearTimeout(timer);
+
+    socket.end();
+
+    return answer;
+  } catch {
+    return null;
+  }
+}

package/src/statusline.ts

@@ -3,6 +3,7 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { statusFile } from './shared/config';
 import { isRecord, sendReport } from './shared/report';
+import { sendBridgeRequest } from './shared/send-bridge-request';
 
 /**
  * Runs as the statusLine command injected into wrangled sessions. Chains the
@@ -60,6 +61,19 @@ export async function runStatusline(): Promise<void> {
     }
   } catch {}
 
+  const segment =
+    process.env['ATC_BRIDGE'] === '1' && sock !== undefined && sock !== ''
+      ? await readOwnSegment(sock)
+      : readFleetSegment();
+
+  const line = [chained, segment].filter((part) => part !== '').join(' \u001B[90m▏\u001B[0m ');
+
+  console.log(line);
+  process.exit(0);
+}
+
+// The fleet segment, from the status file the daemon writes beside it.
+function readFleetSegment(): string {
   let segment = '';
 
   try {
@@ -90,10 +104,27 @@ export async function runStatusline(): Promise<void> {
     }
   } catch {}
 
-  const line = [chained, segment].filter((part) => part !== '').join(' \u001B[90m▏\u001B[0m ');
+  return segment;
+}
 
-  console.log(line);
-  process.exit(0);
+// Inside a remote host the status file is out of reach, and the session
+// bridge returns the session's own state alone, never the rest of the fleet.
+async function readOwnSegment(sock: string): Promise<string> {
+  const status = await sendBridgeRequest(sock, 'status.read', {}, 500);
+
+  if (status === null || status['ok'] !== true) {
+    return '';
+  }
+
+  if (status['state'] === 'needs_you') {
+    return '\u001B[1;31m● needs you\u001B[0m';
+  }
+
+  if (status['state'] === 'done') {
+    return '\u001B[32m✓ done\u001B[0m';
+  }
+
+  return status['state'] === 'running' ? '\u001B[36m◐ running\u001B[0m' : '';
 }
 
 // A user statusline that is atc's own injected command would chain into

package/src/store/fleet-entry.ts

@@ -8,6 +8,7 @@ import type { DaemonID } from '../shared/daemon-id';
 import { isRecord } from '../shared/report';
 import type { SessionID } from '../shared/session-id';
 import { toAgentSessionID } from '../shared/to-agent-session-id';
+import type { SessionWorkspace } from './workspace-materialization';
 
 // One fleet row. The atc session id keys it and stays the same for the
 // session's whole life, across daemon restarts and fleet restores.
@@ -48,6 +49,24 @@ export interface FleetEntry {
   // The identity the target had when the session started on it; a row
   // without one is bound to the implicit `local` target's identity.
   readonly targetIdentity?: string;
+
+  // What the session's workspace was materialized from, for a session
+  // spawned with a workspace source; a fleet write leaves it to the
+  // materialization record that holds it.
+  readonly workspace?: SessionWorkspace;
+
+  // The environment variable names every harness the session starts goes
+  // without, held with its ready workspace; never their values.
+  readonly withheldEnv?: readonly string[];
+
+  // What the operator asked of the harness: absent keeps it running,
+  // `sleep` keeps its host asleep, and `stop` leaves it ended.
+  readonly desired?: 'sleep' | 'stop';
+
+  // The session whose host the harness runs on: its own id, or its
+  // parent's when the two share one host. A row without one runs on a host
+  // of its own.
+  readonly hostKey?: SessionID;
 }
 
 export interface FleetStore {

package/src/store/run-migrations.ts

@@ -5,6 +5,7 @@ import { DEFAULT_MIGRATION_TABLE, Migrator } from 'kysely/migration';
 import type { Migration, MigrationProvider, MigrationResultSet } from 'kysely/migration';
 import type { IdempotencyState } from './idempotency-record';
 import type { MessageStatus } from './message-record';
+import type { MaterializationPhase } from './workspace-materialization';
 
 interface FleetTable {
   session_id: string;
@@ -23,6 +24,15 @@ interface FleetTable {
   effort: string | null;
   target: string | null;
   target_identity: string | null;
+
+  // What the operator asked of the session's harness: null keeps it
+  // running, `sleep` keeps its host asleep, and `stop` leaves it ended.
+  desired: string | null;
+
+  // The session whose host this session's harness runs on: its own id, or
+  // its parent's when the two share one host. Null for a row from before
+  // hosts were recorded, which runs on its own.
+  host_key: string | null;
 }
 
 interface EventsTable {
@@ -34,6 +44,10 @@ interface EventsTable {
   session_id: string | null;
   kind: string | null;
   detail: string | null;
+
+  // The id a remote session's reporter gave a report row, unique so a
+  // resent report lands once; null on every other row.
+  report_id: string | null;
 }
 
 interface SpawnHistoryTable {
@@ -77,6 +91,27 @@ interface IdempotencyTable {
   effect_target_identity: string | null;
 }
 
+// One spawn's workspace on its way to the execution target, keyed by the
+// session it is for.
+interface WorkspaceMaterializationTable {
+  session_id: string;
+  target: string;
+  dir: string;
+  source_kind: 'path' | 'git';
+  phase: MaterializationPhase;
+  repo_url: string | null;
+  sha: string | null;
+  ref: string | null;
+  error_code: string | null;
+  started_at: number;
+  updated_at: number;
+  materialized_at: number | null;
+
+  // JSON array of the environment variable names every harness the session
+  // starts goes without; names only, never their values.
+  withheld_env: string | null;
+}
+
 interface MessagesTable {
   id: string;
   atc_id: string;
@@ -106,6 +141,7 @@ export interface StateStoreSchema {
   messages: MessagesTable;
   session_owner: SessionOwnerTable;
   idempotency: IdempotencyTable;
+  workspace_materialization: WorkspaceMaterializationTable;
 }
 
 // Every shape the fleet table has shipped with: the oldest carries only
@@ -361,6 +397,46 @@ const MIGRATIONS: Record<string, Migration> = {
         .execute();
     },
   },
+  '020_create_workspace_materialization': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema
+        .createTable('workspace_materialization')
+        .ifNotExists()
+        .addColumn('session_id', 'text', (c) => c.primaryKey())
+        .addColumn('target', 'text', (c) => c.notNull())
+        .addColumn('dir', 'text', (c) => c.notNull())
+        .addColumn('source_kind', 'text', (c) => c.notNull())
+        .addColumn('phase', 'text', (c) => c.notNull())
+        .addColumn('repo_url', 'text')
+        .addColumn('sha', 'text')
+        .addColumn('ref', 'text')
+        .addColumn('error_code', 'text')
+        .addColumn('started_at', 'integer', (c) => c.notNull())
+        .addColumn('updated_at', 'integer', (c) => c.notNull())
+        .addColumn('materialized_at', 'integer')
+        .addColumn('withheld_env', 'text')
+        .execute();
+    },
+  },
+  '021_add_fleet_lifecycle': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema.alterTable('fleet').addColumn('desired', 'text').execute();
+      await db.schema.alterTable('fleet').addColumn('host_key', 'text').execute();
+    },
+  },
+  '022_add_events_report_id': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema.alterTable('events').addColumn('report_id', 'text').execute();
+
+      await db.schema
+        .createIndex('events_report_id')
+        .ifNotExists()
+        .unique()
+        .on('events')
+        .column('report_id')
+        .execute();
+    },
+  },
 };
 
 const PROVIDER: MigrationProvider = {