@zgeoff/atc 2.15.0 → 2.15.1

package/src/daemon/daemon-context.ts

@@ -0,0 +1,240 @@
+import type { AgentAdapter, SpawnOptions, SpawnOverrides } from '../agents/agent-adapter';
+import type { EventMsg } from '../protocol/protocol';
+import type { SpawnWorkspaceSource } from '../protocol/request-param-schemas';
+import type { AgentID } from '../shared/agent-id';
+import type { TargetConfigError } from '../shared/collect-targets';
+import type { DaemonID } from '../shared/daemon-id';
+import type { MessageID } from '../shared/message-id';
+import type { SessionID } from '../shared/session-id';
+import type { FleetEntry } from '../store/fleet-entry';
+import type { MessageRecord } from '../store/message-record';
+import type { Dims } from './attach-registry';
+import type { AgentEntry } from './build-agent-list';
+import type { FleetEvent } from './build-fleet-events';
+import type { ReportView } from './build-report-view';
+import type { TargetEntry } from './build-target-list';
+import type { KeyedRequest } from './idempotency-ledger';
+import type { TranscriptPage, TranscriptPosition } from './load-transcript-page';
+import type { AnswerResult } from './permission-registry';
+import type { ScreenText } from './screen-model';
+import type { SessionDescriptor } from './sessions';
+import type { TargetAccess, TargetGrant } from './target-access';
+
+export interface SpawnParams {
+  readonly cwd: string;
+  readonly name: string;
+  readonly prompt: string;
+  readonly cols: number;
+  readonly rows: number;
+  readonly resume: SpawnOptions['resume'];
+  readonly namedBy: 'user' | 'auto';
+  readonly agent: AgentID;
+  readonly parent: SessionID | null;
+  readonly overrides: SpawnOverrides;
+  readonly target: string;
+
+  // Where the session's working directory comes from; null runs the
+  // session in cwd as it stands.
+  readonly workspace: SpawnWorkspaceSource | null;
+}
+
+interface SessionRecord {
+  readonly session: SessionDescriptor;
+  readonly prompt: string | null;
+  readonly lastActivityAt: number;
+  readonly pending: { readonly message: string } | null;
+  readonly result: string | null;
+}
+
+/**
+ * What `session.forget` answers: the token a forget that destroys a host
+ * must carry, with the time it stops being taken; or the forgotten session,
+ * with whether its host was destroyed.
+ */
+type ForgetResult =
+  | { readonly confirmToken: string; readonly expiresAt: number }
+  | { readonly forgotten: true; readonly destroyed: 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 {
+  readonly path: string;
+  readonly page: TranscriptPage;
+}
+
+// The `agents.list` answer: the host the daemon runs on, each agent, each
+// execution target, what a spawn without either runs with, a digest of
+// the target config, and the target config problems the daemon started
+// with.
+interface AgentList {
+  readonly daemon: {
+    readonly hostname: string;
+    readonly platform: string;
+    readonly arch: string;
+    readonly build: string;
+  };
+  readonly agents: readonly AgentEntry[];
+  readonly targets: readonly TargetEntry[];
+  readonly spawnDefaults: { readonly agent: AgentID; readonly target: string | null };
+  readonly configRevision: string;
+  readonly targetErrors: readonly TargetConfigError[];
+}
+
+// The slice of a connection the attach bookkeeping needs: identity plus the
+// ability to receive output events.
+export interface OutputClient {
+  readonly sendOutput: (sessionID: SessionID, event: EventMsg, byteLength: number) => void;
+}
+
+// One `events.read` answer: the events, and whether more follow them.
+interface EventsPage {
+  readonly events: readonly FleetEvent[];
+  readonly more: boolean;
+}
+
+// One message as `message.get` reports it: the session it belongs to now,
+// every field of the record, and the other messages its turn answered.
+interface MessageView {
+  readonly session: SessionID;
+  readonly record: MessageRecord;
+  readonly answeredWith: readonly MessageID[];
+}
+
+// Why a session refuses a message before the daemon accepts it.
+export type MessageRefusal = 'missing' | 'dead' | 'unsupported' | 'no_tap';
+
+// The slice of a connection a tap subscription needs.
+export interface TapClient {
+  readonly sendEvent: (event: EventMsg) => void;
+}
+
+export interface DaemonContext {
+  readonly build: string;
+  readonly daemonID: DaemonID;
+  readonly collectSessions: () => SessionDescriptor[];
+  readonly collectSpawnDirs: () => Promise<string[]>;
+  readonly collectAgents: () => AgentList;
+  readonly collectFleet: () => Promise<FleetEntry[]>;
+  readonly loadLastUsedAgent: () => Promise<AgentID>;
+  readonly findAdapter: (id: AgentID) => AgentAdapter | null;
+
+  // The targets a principal may use.
+  readonly buildTargetAccess: (principal: string) => TargetAccess;
+
+  // The target and identity a session is bound to, or null when no
+  // session holds the id.
+  readonly findSessionGrant: (id: SessionID) => TargetGrant | null;
+
+  // The identity a target holds now, or null when the config holds no such
+  // target.
+  readonly findTargetIdentity: (target: string) => string | null;
+
+  // The ids of a session's sub-sessions.
+  readonly collectChildIDs: (id: SessionID) => SessionID[];
+
+  // The session a permission request belongs to, answered or not, or null
+  // for an unknown request.
+  readonly findPermissionSession: (request: string) => SessionID | null;
+
+  // The target a spawn runs on: the one it names, else the default. Throws
+  // the refusal for a target the spawn cannot run on, and for a spawn
+  // without a target when the config gives no default.
+  readonly resolveSpawnTarget: (requested: string | undefined) => string;
+
+  // Throws the refusal for a target that cannot materialize a workspace:
+  // one whose provider cannot both transfer an archive and run a command.
+  readonly requireWorkspaceTarget: (target: string) => void;
+
+  // Runs the plan, which throws the refusal for a spawn it refuses, then
+  // spawns. Answers with the `session.spawn` ok payload, which a keyed
+  // retry replays as the first spawn answered it while the access, when
+  // there is one, still reaches the target the spawn's session was bound to.
+  readonly spawnSession: (
+    plan: () => SpawnParams,
+    keyed: KeyedRequest | null,
+    access: TargetAccess | null,
+  ) => Promise<Readonly<Record<string, unknown>>>;
+  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.
+  readonly forgetSession: (
+    id: SessionID,
+    confirmToken: string | undefined,
+  ) => Promise<ForgetResult | 'missing'>;
+  readonly updateSession: (id: SessionID, name?: string, pinned?: boolean) => boolean | 'child_pin';
+  readonly quitDaemon: () => void;
+  readonly ackSession: (id: SessionID) => boolean;
+  readonly buildResumeCommand: (id: SessionID) => string | null;
+  readonly readSessionScreen: (id: SessionID) => Promise<ScreenText | 'missing' | 'no_screen'>;
+  readonly answerPermission: (request: string, decision: string) => AnswerResult;
+  readonly restoreFleet: (cols: number, rows: number) => Promise<number>;
+  readonly attachSession: (
+    client: OutputClient,
+    sessionID: SessionID,
+    dims: Dims,
+  ) => 'ok' | 'missing' | 'dead';
+  readonly detachSession: (client: OutputClient, sessionID: SessionID) => void;
+  readonly detachClient: (client: OutputClient) => void;
+  readonly writeSessionInput: (
+    sessionID: SessionID,
+    data: string,
+  ) => 'busy' | 'ok' | 'missing' | 'dead';
+
+  // Types a line into the session and submits it the way the session's
+  // agent accepts a line, as opposed to the raw bytes the input write takes.
+  readonly writeSessionLine: (
+    sessionID: SessionID,
+    text: string,
+  ) => 'busy' | 'ok' | 'missing' | 'dead';
+  readonly ejectSession: (
+    id: SessionID,
+    prompt: string,
+  ) => 'ok' | 'missing' | 'unsupported' | 'no_transcript';
+  readonly adoptSession: (
+    id: SessionID,
+    cols: number,
+    rows: number,
+  ) => Promise<'ok' | 'missing' | 'no_transcript'>;
+  readonly resizeSession: (client: OutputClient, sessionID: SessionID, dims: Dims) => boolean;
+  readonly resyncClient: (sessionID: SessionID, client: OutputClient) => Promise<void>;
+  readonly queueBytes?: number;
+  readonly getEffectiveDims: (sessionID: SessionID) => Dims;
+  readonly readSessionRecord: (id: SessionID) => Promise<SessionRecord | 'missing'>;
+  readonly loadSessionTranscript: (
+    id: SessionID,
+    from: TranscriptPosition | null,
+    limit: number,
+  ) => Promise<SessionTranscriptRead | 'missing' | 'unsupported'>;
+
+  // Reads the trail, leaving out each event of a session outside the access
+  // when there is one.
+  readonly readEvents: (
+    afterID: number | null,
+    limit: number,
+    waitMs: number,
+    sessionID: SessionID | null,
+    access: TargetAccess | null,
+  ) => Promise<EventsPage>;
+
+  // One report by the trail id of its event, or null for a trail id that
+  // holds no report, or whose report's session is outside the access when
+  // there is one.
+  readonly readReport: (id: number, access: TargetAccess | null) => Promise<ReportView | null>;
+
+  // Answers with the `session.message` ok payload, which a keyed retry
+  // replays with the message's current status, or with the refusal.
+  readonly writeSessionMessage: (
+    sessionID: SessionID,
+    from: string,
+    text: string,
+    keyed: KeyedRequest | null,
+  ) => Promise<Readonly<Record<string, unknown>> | MessageRefusal>;
+  readonly readMessage: (messageID: MessageID, waitMs: number) => Promise<MessageView | null>;
+  readonly attachTap: (client: TapClient, sessionID: SessionID) => 'ok' | 'missing' | 'unsupported';
+  readonly ackMessage: (
+    client: TapClient,
+    sessionID: SessionID,
+    messageID: MessageID,
+  ) => Promise<MessageRecord | 'not_tapping' | 'unknown'>;
+}

package/src/daemon/daemon.ts

@@ -2,12 +2,15 @@ import { randomUUID } from 'node:crypto';
 import { unlinkSync, writeFileSync } from 'node:fs';
 import { hostname, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
-import type { AdapterEvent, AgentAdapter } from '../agents/agent-adapter';
+import type { AgentAdapter } from '../agents/agent-adapter';
 import { planTypedLineInput } from '../agents/plan-typed-line-input';
+import type { AdapterEvent } from '../protocol/adapter-event';
 import { DaemonError } from '../protocol/daemon-error';
+import type { HookEvent } from '../protocol/hook-event';
 import { MAX_CHUNK, PROTOCOL_V } from '../protocol/protocol';
 import type { EventMsg } from '../protocol/protocol';
 import type { SpawnWorkspaceSource } from '../protocol/request-param-schemas';
+import type { SessionState } from '../protocol/session-state';
 import type { HooksConfig } from '../shared/collect-hooks';
 import type { TargetConfigError } from '../shared/collect-targets';
 import { findDaemonRecord } from '../shared/find-daemon-record';
@@ -47,11 +50,10 @@ import type {
   OutputClient,
   SpawnParams,
   TapClient,
-} from './daemon-connection';
+} from './daemon-context';
 import { EffectRemainsError } from './effect-remains-error';
 import { EventSignal } from './event-signal';
 import { startHookServer } from './hooks';
-import type { HookEvent } from './hooks';
 import { IdempotencyLedger } from './idempotency-ledger';
 import { loadTranscriptPage } from './load-transcript-page';
 import { makeHookRunner } from './make-hook-runner';
@@ -66,7 +68,7 @@ import { runEjectHandoff } from './run-eject-handoff';
 import { ScreenModel } from './screen-model';
 import { SessionRuntime } from './session-runtime';
 import { SessionManager } from './sessions';
-import type { Session, SessionDescriptor, SessionState } from './sessions';
+import type { Session, SessionDescriptor } from './sessions';
 import { startEventsServer } from './start-events-server';
 import { startHeadlessTurn } from './start-headless-turn';
 import { startSessionBridge } from './start-session-bridge';
@@ -972,7 +974,9 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     );
   };
 
-  const ledger = new IdempotencyLedger(store, LOCAL_PRINCIPAL);
+  const ledger = new IdempotencyLedger(store, LOCAL_PRINCIPAL, (line) => {
+    mgr.log(line);
+  });
 
   // Throws the refusal a fresh spawn to the target gets when the access
   // does not reach the target, and the identity, a held spawn key recorded

package/src/daemon/execution-provider.ts

@@ -167,8 +167,20 @@ export interface HarnessHandle {
   ) => HarnessSubscription;
   readonly write: (data: string) => void;
   readonly resize: (cols: number, rows: number) => void;
+
+  // Sends the harness's process the signal that ends it, and returns without
+  // waiting for it to exit.
   readonly kill: () => void;
 
+  // Ends the harness's process with a signal it cannot catch or ignore, on
+  // a provider that can send one; absent on a provider that cannot.
+  readonly killForced?: () => void;
+
+  // Resolves true once the harness's process has exited, and false when the
+  // wait runs out first or the harness stops being followed without an
+  // exit, such as a host that went to sleep with the process inside.
+  readonly waitForExit: (timeoutMs: number) => Promise<boolean>;
+
   // Stops following the harness and leaves its process running, for a host
   // that keeps it after the daemon lets go; on a host that cannot keep it,
   // the process ends as a kill ends it. No listener fires after a detach.

package/src/daemon/hooks.ts

@@ -1,15 +1,9 @@
 import { unlinkSync } from 'node:fs';
+import type { HookEvent } from '../protocol/hook-event';
 import { LineDecoder } from '../protocol/line-decoder';
 import { socketPath } from '../shared/config';
-import type { SessionID } from '../shared/session-id';
 import { parseHookLine } from './parse-hook-line';
 
-export interface HookEvent {
-  atcId: SessionID;
-  event: string;
-  payload: Record<string, unknown>;
-}
-
 // Per-connection read state: the connection's own line framing.
 interface HookConnection {
   readonly lines: LineDecoder;

package/src/daemon/idempotency-ledger.ts

@@ -23,7 +23,9 @@ interface IdempotentCall<T> {
   // effect may still stand, so the claim is kept as outcome_unknown.
   readonly start: () => T | Promise<T>;
 
-  // Resolves once the effect is durable; the claim completes only after.
+  // Resolves once the effect is durable; the claim completes only after. A
+  // settle that throws leaves the effect standing, so the answer is
+  // outcome_unknown and the claim stays held.
   readonly settle: () => Promise<void>;
 
   // The answer to a retry of a completed key.
@@ -43,19 +45,27 @@ interface IdempotentCall<T> {
  * answer; one with a different payload is `idempotency_conflict`; one whose
  * effect a stopped daemon may or may not have run is `outcome_unknown` with
  * the effect id in `data.effectRef`, and never starts the effect again.
+ * An effect that may still stand once its request fails is answered with
+ * `outcome_unknown` and its effect id even when recording that outcome
+ * fails: the claim stays held either way, and the failed write goes to the
+ * log.
  */
 export class IdempotencyLedger {
   private readonly store: StateStore;
 
   private readonly principal: string;
 
+  // Where a failed write to the ledger is reported, one line at a time.
+  private readonly log: (line: string) => void;
+
   // One promise chain per key, so two requests under the same key never
   // interleave their claim and completion on one daemon.
   private readonly locks = new Map<string, Promise<void>>();
 
-  constructor(store: StateStore, principal: string) {
+  constructor(store: StateStore, principal: string, log: (line: string) => void) {
     this.store = store;
     this.principal = principal;
+    this.log = log;
   }
 
   async run<T extends Readonly<Record<string, unknown>>>(call: IdempotentCall<T>): Promise<T> {
@@ -114,13 +124,11 @@ export class IdempotencyLedger {
       result = await call.start();
     } catch (error) {
       if (error instanceof EffectRemainsError) {
-        await this.store.updateIdempotencyOutcomeUnknown(id, Date.now());
+        this.logFailure(call, 'start', error);
+
+        await this.tryRecordOutcomeUnknown(call, id);
 
-        throw new DaemonError(
-          'outcome_unknown',
-          `the ${call.operation} under idempotency key '${call.keyed.key}' failed and its effect may still stand; check ${call.effectRef} before retrying under a new key`,
-          { effectRef: call.effectRef },
-        );
+        throw buildOutcomeUnknownError(call, 'failed');
       }
 
       await this.store.removeIdempotencyKey(id);
@@ -128,20 +136,61 @@ export class IdempotencyLedger {
       throw error;
     }
 
-    // A settle that fails leaves the claim in progress: the effect started,
-    // so the next daemon start marks its outcome unknown rather than letting
-    // a retry run it again.
-    await call.settle();
+    // From here the effect stands. A settle or completion that fails keeps
+    // the claim in progress, so a retry answers outcome_unknown rather than
+    // running the effect again.
+    try {
+      await call.settle();
+    } catch (error) {
+      this.logFailure(call, 'settle', error);
+
+      await this.tryRecordOutcomeUnknown(call, id);
 
-    await this.store.updateIdempotencyCompleted(
-      id,
-      JSON.stringify(result),
-      Date.now(),
-      call.findEffectTarget?.(result) ?? null,
-    );
+      throw buildOutcomeUnknownError(call, 'could not be made durable');
+    }
+
+    try {
+      await this.store.updateIdempotencyCompleted(
+        id,
+        JSON.stringify(result),
+        Date.now(),
+        call.findEffectTarget?.(result) ?? null,
+      );
+    } catch (error) {
+      this.logFailure(call, 'completion write', error);
+      throw buildOutcomeUnknownError(call, 'could not be recorded as completed');
+    }
 
     return result;
   }
+
+  // A claim this write fails to update stays in progress, which a retry
+  // answers the same way, so the failure is logged and not thrown.
+  private async tryRecordOutcomeUnknown(
+    call: Pick<IdempotentCall<unknown>, 'operation' | 'keyed' | 'effectRef'>,
+    id: Pick<IdempotencyRecord, 'principal' | 'operation' | 'key'>,
+  ): Promise<void> {
+    try {
+      await this.store.updateIdempotencyOutcomeUnknown(id, Date.now());
+    } catch (error) {
+      this.logFailure(call, 'outcome_unknown write', error);
+    }
+  }
+
+  // The line holds the operation, key, effect id, the step that failed, and
+  // the error, never the request's payload or the effect's result.
+  private logFailure(
+    call: Pick<IdempotentCall<unknown>, 'operation' | 'keyed' | 'effectRef'>,
+    step: string,
+    error: unknown,
+  ): void {
+    const cause =
+      error instanceof Error && error.cause instanceof Error ? ` (${String(error.cause)})` : '';
+
+    this.log(
+      `atc ${call.operation} under idempotency key '${call.keyed.key}' (effect ${call.effectRef}): ${step} failed: ${String(error)}${cause}`,
+    );
+  }
 }
 
 function answerHeldKey<T>(call: IdempotentCall<T>, held: IdempotencyRecord): T | Promise<T> {
@@ -162,3 +211,14 @@ function answerHeldKey<T>(call: IdempotentCall<T>, held: IdempotencyRecord): T |
     { effectRef: held.effectRef },
   );
 }
+
+function buildOutcomeUnknownError(
+  call: Pick<IdempotentCall<unknown>, 'operation' | 'keyed' | 'effectRef'>,
+  what: string,
+): DaemonError {
+  return new DaemonError(
+    'outcome_unknown',
+    `the ${call.operation} under idempotency key '${call.keyed.key}' ${what} and its effect may still stand; check ${call.effectRef} before retrying under a new key`,
+    { effectRef: call.effectRef },
+  );
+}

package/src/daemon/imp-harness.ts

@@ -99,6 +99,15 @@ export class ImpHarness implements HarnessHandle {
 
   private killPending = false;
 
+  // Whether the process exited, once the harness stops being followed, and
+  // the waits on that answer until then.
+  private exitConfirmed: boolean | null = null;
+
+  private readonly exitWaiters = new Set<{
+    readonly waited: PromiseWithResolvers<boolean>;
+    readonly timer: ReturnType<typeof setTimeout>;
+  }>();
+
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
 
   // The terminal size the open connection's request asked for.
@@ -175,6 +184,28 @@ export class ImpHarness implements HarnessHandle {
     }
   };
 
+  // Only an exit impd reports counts: a host that lost the process or went
+  // to sleep with it inside confirms nothing.
+  readonly waitForExit = (timeoutMs: number): Promise<boolean> => {
+    if (this.exitConfirmed !== null) {
+      return Promise.resolve(this.exitConfirmed);
+    }
+
+    const waited = Promise.withResolvers<boolean>();
+
+    const waiter = {
+      waited,
+      timer: setTimeout(() => {
+        this.exitWaiters.delete(waiter);
+        waited.resolve(false);
+      }, timeoutMs),
+    };
+
+    this.exitWaiters.add(waiter);
+
+    return waited.promise;
+  };
+
   readonly detach = (): void => {
     if (this.done) {
       return;
@@ -521,6 +552,8 @@ export class ImpHarness implements HarnessHandle {
   private emitExit(exit: HarnessExit): void {
     const listeners = [...this.exitListeners];
 
+    this.exitConfirmed = exit.reason === undefined || exit.reason === 'exited';
+
     this.stopFollowing();
 
     for (const listener of listeners) {
@@ -537,7 +570,15 @@ export class ImpHarness implements HarnessHandle {
 
     this.done = true;
     this.connection = null;
+    this.exitConfirmed ??= false;
+
+    for (const waiter of this.exitWaiters) {
+      clearTimeout(waiter.timer);
+
+      waiter.waited.resolve(this.exitConfirmed);
+    }
 
+    this.exitWaiters.clear();
     this.dataListeners.clear();
     this.exitListeners.clear();
     this.attachmentListeners.clear();

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

@@ -74,6 +74,35 @@ export class LocalPTYProvider implements ExecutionProvider {
       kill: () => {
         pty.kill();
       },
+
+      // A process already gone has nothing left to end.
+      killForced: () => {
+        try {
+          process.kill(pty.pid, 'SIGKILL');
+        } catch (error) {
+          if (!isMissingProcessError(error)) {
+            throw error;
+          }
+        }
+      },
+
+      // bun-pty's kill sends one SIGHUP and reports an exit at once, whether
+      // the process ended or not, so the exit is read from the process id
+      // instead: the library reaps its child, so the id stops answering a
+      // signal once the process is gone.
+      waitForExit: async (timeoutMs) => {
+        const deadline = Date.now() + timeoutMs;
+
+        while (isProcessRunning(pty.pid)) {
+          if (Date.now() >= deadline) {
+            return false;
+          }
+
+          await Bun.sleep(20);
+        }
+
+        return true;
+      },
       detach: () => {
         for (const subscription of subscriptions) {
           subscription.dispose();
@@ -140,3 +169,19 @@ export class LocalPTYProvider implements ExecutionProvider {
     return { exitCode, stdout, stderr };
   }
 }
+
+// A process another user owns still runs, so only a missing process counts
+// as gone.
+function isProcessRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+
+    return true;
+  } catch (error) {
+    return !isMissingProcessError(error);
+  }
+}
+
+function isMissingProcessError(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ESRCH';
+}

package/src/daemon/parse-hook-line.ts

@@ -1,6 +1,6 @@
+import type { HookEvent } from '../protocol/hook-event';
 import { isRecord } from '../shared/report';
 import { toSessionID } from '../shared/to-session-id';
-import type { HookEvent } from './hooks';
 
 /**
  * One reporter line as a hook event, or null for a line that is not one.