@zgeoff/atc 2.25.0 → 2.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.25.0",
+  "version": "2.26.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/agents/gateway-adapter.ts

@@ -5,11 +5,16 @@ import type { AgentID } from '../shared/agent-id';
 import type { AgentSessionID } from '../shared/agent-session-id';
 import type { GatewayConfig } from '../shared/collect-gateways';
 import type { Config } from '../shared/config';
+import { isBrokerVariable } from '../shared/is-broker-variable';
+import { isRecord } from '../shared/report';
+import { resolveAuthProfiles } from '../shared/resolve-auth-profiles';
 import { toShellArg } from '../shared/to-shell-arg';
 import type {
   AgentAdapter,
   AgentProfile,
   AuthSelection,
+  GuestPaths,
+  GuestSpawnPlan,
   HeadlessRunner,
   NameUpdate,
   ResumeCheck,
@@ -17,10 +22,13 @@ import type {
   SpawnOptions,
   SpawnPlan,
 } from './agent-adapter';
+import { buildATCBridgeFiles } from './build-atc-bridge-files';
 import { buildClaudeOverrideArgs } from './build-claude-override-args';
+import { buildHookSettings } from './build-hook-settings';
 import { buildRestoreModeArgs } from './build-restore-mode-args';
 import { ClaudeAdapter } from './claude-adapter';
 import { CLAUDE_EFFORT_LEVELS } from './claude-effort-levels';
+import { findClaudePermissionMode } from './find-claude-permission-mode';
 import { findFlagValue } from './find-flag-value';
 import { makeClaudeHeadlessRunner } from './make-claude-headless-runner';
 import type { ClaudeHeadlessRun } from './make-claude-headless-runner';
@@ -106,19 +114,20 @@ export class GatewayAdapter implements AgentAdapter {
           });
   }
 
-  // A gateway whose credential comes through impd's broker starts only in a
-  // guest that reaches the broker, with guest settings the adapter plans
-  // for it, and it plans none: started without them, the CLI would send
-  // whatever credential it holds to the gateway's host.
+  // A gateway whose credential comes through impd's broker is refused
+  // before anything is prepared for it when its placeholders cannot pair
+  // with the broker's header, or when its settings env would route the CLI
+  // around the broker.
   findSpawnRefusal(): DaemonError | null {
-    if (this.gateway.auth === undefined) {
+    const auth = this.gateway.auth;
+
+    if (auth === undefined) {
       return null;
     }
 
-    return new DaemonError(
-      'auth_target_unsupported',
-      `gateway '${this.id}' takes its credential from impd's broker, and atc plans no guest settings for it on any target`,
-      { agent: this.id },
+    return (
+      this.findPlaceholderRefusal(auth.placeholderEnv, auth.profiles) ??
+      this.findSettingsEnvConflict()
     );
   }
 
@@ -135,29 +144,101 @@ export class GatewayAdapter implements AgentAdapter {
     };
   }
 
+  // A gateway whose credential comes through impd's broker never starts on
+  // the daemon's machine: started without the broker, the CLI would send
+  // whatever credential it holds to the gateway's host.
   planSpawn(opts: SpawnOptions): SpawnPlan {
+    if (this.gateway.auth !== undefined) {
+      throw this.buildBrokerRefusal('which only an imp target can give it');
+    }
+
+    const modeArgs =
+      opts.resume === false ? [] : buildRestoreModeArgs(this.gateway.args, this.gateway.settings);
+
     return {
       bin: this.gateway.bin,
-      args: [
-        ...buildClaudeOverrideArgs(this.gateway.args, opts),
-        ...(opts.resume === false
-          ? []
-          : buildRestoreModeArgs(this.gateway.args, this.gateway.settings)),
-        '--settings',
-        this.writeSettings(),
-        '--plugin-dir',
-        this.writeBridge(),
-        ...(opts.resume === true ? ['--resume'] : []),
-        ...(typeof opts.resume === 'string' ? ['--resume', opts.resume] : []),
-        ...(opts.prompt === '' ? [] : [opts.prompt]),
-      ],
+      args: this.buildArgs(opts, modeArgs, this.writeSettings(), this.writeBridge()),
     };
   }
 
-  // The credential helper runs on the daemon's machine, so a gateway
-  // session never runs on a remote host.
-  planGuestSpawn(): null {
-    return null;
+  // A gateway whose credential comes through impd's broker runs on a
+  // remote host with a settings file of the session's own per binding
+  // revision, a Claude config folder of its own that holds no account,
+  // and placeholders in place of the credential, which the broker swaps
+  // for the real one on the host's side. A shell seeds the config folder
+  // before it runs the CLI, since a transferred file would replace the
+  // state an earlier run left. Any other gateway's credential
+  // helper runs on the daemon's machine, so it never runs remotely.
+  planGuestSpawn(opts: SpawnOptions, guest: GuestPaths): GuestSpawnPlan | null {
+    if (this.gateway.auth === undefined) {
+      return null;
+    }
+
+    if (guest.auth === undefined) {
+      throw this.buildBrokerRefusal('and this session has no broker binding');
+    }
+
+    if (guest.atc === null) {
+      return null;
+    }
+
+    const refusal =
+      this.findPlaceholderRefusal(guest.auth.env, this.gateway.auth.profiles) ??
+      this.findSettingsEnvConflict();
+
+    if (refusal !== null) {
+      throw refusal;
+    }
+
+    const argv = [guest.atc];
+    const settingsPath = `auth-r${guest.auth.revision}/settings.json`;
+
+    const bridge = Object.entries(buildATCBridgeFiles(argv)).map(
+      ([path, content]): [string, string] => [`atc-bridge/${path}`, content],
+    );
+
+    const settings = buildHookSettings(
+      {
+        id: this.id,
+        env: {
+          ...this.gateway.env,
+          ANTHROPIC_BASE_URL: this.gateway.baseURL,
+          ...guest.auth.env,
+          CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
+        },
+        ...(this.gateway.settings === undefined
+          ? {}
+          : { settings: buildSettingsWithoutHelper(this.gateway.settings) }),
+      },
+      0,
+      argv,
+    );
+
+    const configDir = `${guest.dir}/${CLAUDE_CONFIG_FOLDER}`;
+
+    return {
+      bin: 'sh',
+      args: [
+        '-c',
+        SEED_CONFIG_SCRIPT,
+        'sh',
+        configDir,
+        `${guest.dir}/${CONFIG_SEED_FILE}`,
+        this.gateway.bin,
+        ...this.buildArgs(
+          opts,
+          this.buildGuestModeArgs(),
+          `${guest.dir}/${settingsPath}`,
+          `${guest.dir}/atc-bridge`,
+        ),
+      ],
+      files: {
+        [settingsPath]: JSON.stringify(settings, null, 2),
+        [CONFIG_SEED_FILE]: JSON.stringify(ONBOARDED_CONFIG, null, 2),
+        ...Object.fromEntries(bridge),
+      },
+      env: { CLAUDE_CONFIG_DIR: configDir, ...guest.auth.env },
+    };
   }
 
   normalizeHook(e: HookEvent): AdapterEvent {
@@ -197,6 +278,117 @@ export class GatewayAdapter implements AgentAdapter {
     return `cd ${toShellArg(cwd)} && ${this.gateway.bin}${args} --settings ${settings} --resume${resume}`;
   }
 
+  private buildArgs(
+    opts: SpawnOptions,
+    modeArgs: readonly string[],
+    settings: string,
+    pluginDir: string,
+  ): string[] {
+    return [
+      ...buildClaudeOverrideArgs(this.gateway.args, opts),
+      ...modeArgs,
+      '--settings',
+      settings,
+      '--plugin-dir',
+      pluginDir,
+      ...(opts.resume === true ? ['--resume'] : []),
+      ...(typeof opts.resume === 'string' ? ['--resume', opts.resume] : []),
+      ...(opts.prompt === '' ? [] : [opts.prompt]),
+    ];
+  }
+
+  // A brokered session's Claude config is fresh, so the CLI's own default
+  // mode would apply rather than the one the owner's settings set. Every
+  // start therefore names its mode: the one the gateway's arguments or
+  // settings set, else the CLI's manual mode, which asks before each
+  // action.
+  private buildGuestModeArgs(): string[] {
+    if (findFlagValue(this.gateway.args, ['--permission-mode']) !== null) {
+      return [];
+    }
+
+    return [
+      '--permission-mode',
+      findClaudePermissionMode([], this.gateway.settings) ?? MANUAL_PERMISSION_MODE,
+    ];
+  }
+
+  private buildBrokerRefusal(reason: string): DaemonError {
+    return new DaemonError(
+      'auth_target_unsupported',
+      `gateway '${this.id}' takes its credential from impd's broker, ${reason}`,
+      { agent: this.id },
+    );
+  }
+
+  // The Claude CLI sends ANTHROPIC_AUTH_TOKEN as a bearer authorization
+  // header, the one pairing atc binds, so the placeholders must be that
+  // variable alone, holding the placeholder, for a profile whose rule on
+  // the base URL's host sets that header. Any other variable would put the
+  // placeholder in a header the broker never fills.
+  private findPlaceholderRefusal(
+    env: Readonly<Record<string, string>>,
+    profiles: readonly string[],
+  ): DaemonError | null {
+    const keys = Object.keys(env);
+
+    if (keys.length !== 1 || keys[0] !== BEARER_VARIABLE) {
+      return this.buildPlaceholderRefusal(
+        `needs ${BEARER_VARIABLE} as its only placeholder variable, which the broker fills as a bearer authorization header; it has ${keys.length === 0 ? 'none' : keys.join(', ')}`,
+      );
+    }
+
+    if (env[BEARER_VARIABLE] !== PLACEHOLDER) {
+      return this.buildPlaceholderRefusal(`needs ${BEARER_VARIABLE} to hold ${PLACEHOLDER}`);
+    }
+
+    const resolution = resolveAuthProfiles(this.config.authProfiles, profiles);
+
+    const host = new URL(this.gateway.baseURL).hostname;
+
+    const rule =
+      'resolved' in resolution
+        ? resolution.resolved.secrets.flatMap((s) => s.rules).find((r) => r.host === host)
+        : undefined;
+
+    if (rule?.header !== 'authorization' || rule.scheme !== 'bearer') {
+      return this.buildPlaceholderRefusal(
+        `needs a profile that sets a bearer authorization header for ${host}, the header ${BEARER_VARIABLE} fills`,
+      );
+    }
+
+    return null;
+  }
+
+  // The settings file's env block reaches the CLI's own process, so a proxy
+  // or CA variable there would route the CLI around the broker.
+  private findSettingsEnvConflict(): DaemonError | null {
+    const settingsEnv = this.gateway.settings?.['env'];
+
+    const keys = [
+      ...Object.keys(this.gateway.env),
+      ...(isRecord(settingsEnv) ? Object.keys(settingsEnv) : []),
+    ];
+
+    const variable = keys.find((key) => isBrokerVariable(key));
+
+    if (variable === undefined) {
+      return null;
+    }
+
+    return new DaemonError(
+      'auth_target_unsupported',
+      `gateway '${this.id}' sets ${variable} in its settings env, which would route around impd's broker`,
+      { agent: this.id, problem: 'guest_env_conflict', variable },
+    );
+  }
+
+  private buildPlaceholderRefusal(problem: string): DaemonError {
+    return new DaemonError('auth_placeholder_unsupported', `gateway '${this.id}' ${problem}`, {
+      agent: this.id,
+    });
+  }
+
   private writeSettings(): string {
     this.settingsFile ??= writeHookSettings({
       id: this.id,
@@ -217,6 +409,43 @@ export class GatewayAdapter implements AgentAdapter {
   }
 }
 
+// The variable the Claude CLI sends as a bearer authorization header, and
+// the value impd's broker replaces with the credential on the host's side.
+const BEARER_VARIABLE = 'ANTHROPIC_AUTH_TOKEN';
+const PLACEHOLDER = 'imp-broker-placeholder';
+
+// The Claude CLI's mode that asks a person before each action.
+const MANUAL_PERMISSION_MODE = 'default';
+
+// The Claude config folder a brokered session gets inside its guest
+// folder, so no account or setting of the host's image reaches it.
+const CLAUDE_CONFIG_FOLDER = 'claude-config';
+
+// The state the Claude CLI reads from its config folder's `.claude.json`
+// to start without its first-run onboarding. It holds no account: the
+// placeholder credential is what keeps the CLI from asking for a login.
+// It holds no folder trust either, so the CLI asks a person to trust the
+// workspace on its first start.
+const ONBOARDED_CONFIG = { hasCompletedOnboarding: true };
+
+// Where that state travels, beside the config folder rather than in it.
+const CONFIG_SEED_FILE = 'claude-config-seed.json';
+
+// Copies the seed into the config folder only when the folder holds no
+// `.claude.json` yet, then runs the CLI. A resumed session keeps the state
+// the CLI wrote, a folder trust a person accepted included. The arguments
+// are the config folder, the seed, and the CLI's own command line.
+const SEED_CONFIG_SCRIPT =
+  'mkdir -p "$1" && { [ -e "$1/.claude.json" ] || cp "$2" "$1/.claude.json"; } && shift 2 && exec "$@"';
+
+// The gateway's settings without a credential helper, which a brokered
+// session never runs.
+function buildSettingsWithoutHelper(
+  settings: Readonly<Record<string, unknown>>,
+): Readonly<Record<string, unknown>> {
+  return Object.fromEntries(Object.entries(settings).filter(([key]) => key !== 'apiKeyHelper'));
+}
+
 // The model names a gateway's env sets explicitly, keyed by role:
 // `ANTHROPIC_MODEL` is `default`, and `ANTHROPIC_DEFAULT_<TIER>_MODEL` is the
 // tier in lower case. No other env value leaves the adapter.

package/src/client/collect-agent-picks.ts

@@ -9,8 +9,7 @@ export interface AgentPick {
 /**
  * The agent choices the spawn and adopt flows offer, in menu order. An agent
  * whose configured binary does not resolve is left out, so every row in the
- * menu is a session that can start. A gateway with auth is left out too, since
- * every start of one is refused. Resolution follows the rule a spawn
+ * menu is a session that can start. Resolution follows the rule a spawn
  * follows: a bare name comes off PATH, a name carrying a separator is taken
  * as a path, and either way it has to be executable.
  */
@@ -23,9 +22,7 @@ export function collectAgentPicks(config: Config): AgentPick[] {
     { agent: 'claude', label: 'Claude', bin: config.claudeBin },
     { agent: 'grok', label: 'Grok', bin: config.grokBin },
     { agent: 'codex', label: 'Codex', bin: config.codexBin },
-    ...config.gateways
-      .filter((g) => g.auth === undefined)
-      .map((g) => ({ agent: g.id, label: g.label, bin: g.bin })),
+    ...config.gateways.map((g) => ({ agent: g.id, label: g.label, bin: g.bin })),
   ];
 
   return candidates

package/src/daemon/daemon-connection.ts

@@ -74,9 +74,15 @@ interface PeerSocket extends SocketWriter {
 export interface TCPPeer {
   readonly verifyHandshake: (presented: string | null) => Promise<string | null>;
 
-  // Counts a line other than a handshake, sent before one passed, as a
-  // failed handshake from the peer's address.
-  readonly recordFailure: () => void;
+  // Counts a line other than a handshake, or one over the size cap, sent
+  // before a handshake passed, as a failed handshake from the peer's
+  // address.
+  readonly recordFailure: (reason: 'unexpected_line' | 'line_too_long') => void;
+
+  // Records a handshake or a request refused for a principal the config
+  // does not list. The principal itself is never logged: an unlisted one
+  // is whatever the peer sent, a credential included.
+  readonly recordRefusedPrincipal: () => void;
 }
 
 export class DaemonConnection {
@@ -220,7 +226,7 @@ export class DaemonConnection {
     const oversized = this.lines.pendingLength + chunk.length > MAX_LINE;
 
     if (oversized && this.isUnauthenticatedTCP()) {
-      this.tcp?.recordFailure();
+      this.tcp?.recordFailure('line_too_long');
       this.peer.end();
 
       return;
@@ -337,7 +343,7 @@ export class DaemonConnection {
       const isHello = decoded.kind === 'request' && decoded.msg.m === 'daemon.hello';
 
       if (this.tcpHelloSent || !isHello) {
-        this.tcp?.recordFailure();
+        this.tcp?.recordFailure('unexpected_line');
 
         return 'close';
       }
@@ -386,6 +392,7 @@ export class DaemonConnection {
     }
 
     if (!this.ctx.hasListedPrincipal(req.as)) {
+      this.tcp?.recordRefusedPrincipal();
       this.sendErr(req.id, 'unauthorized', `principal '${req.as}' is not listed in principals`);
 
       return;
@@ -1669,6 +1676,8 @@ export class DaemonConnection {
       const principal = parsedHello.data.principal ?? null;
 
       if (principal !== null && !this.ctx.hasListedPrincipal(principal)) {
+        tcp.recordRefusedPrincipal();
+
         this.sendErr(
           req.id,
           'unauthorized',

package/src/daemon/daemon.ts

@@ -69,6 +69,7 @@ import { loadListenerTokens } from './load-listener-tokens';
 import { loadTranscriptPage } from './load-transcript-page';
 import { makeHookRunner } from './make-hook-runner';
 import type { HookScope } from './make-hook-runner';
+import { makeNonBlockingLog } from './make-non-blocking-log';
 import { materializeWorkspace } from './materialize-workspace';
 import { mintMessageID } from './mint-message-id';
 import { mintSessionID } from './mint-session-id';
@@ -192,6 +193,16 @@ interface ListenOptions {
   // How many delayed handshakes may wait at once across every address; 64
   // when unset.
   readonly maxDelayedHandshakes?: number;
+
+  // The clock the refusal log reads, Date.now when unset, and how long it
+  // folds repeated refusals from one peer into one line; a minute when
+  // unset.
+  readonly now?: () => number;
+  readonly refusalLogIntervalMs?: number;
+
+  // How many peers and kinds of refusal the refusal log tracks at once;
+  // 1024 when unset.
+  readonly maxRefusalWindows?: number;
 }
 
 export interface DaemonHandle {
@@ -231,6 +242,17 @@ const HANDSHAKE_FAILURE_DELAY_MS = 10_000;
 // refused at once.
 const MAX_DELAYED_HANDSHAKES = 64;
 
+// How long the TCP listener folds repeated refusals from one peer into one
+// log line.
+const REFUSAL_LOG_INTERVAL_MS = 60_000;
+
+// How many peers and kinds of refusal the TCP listener's refusal log tracks
+// at once.
+const MAX_REFUSAL_WINDOWS = 1024;
+
+// Where the TCP listener logs when the daemon is given no log.
+const STDERR_FD = 2;
+
 // How long startup waits for a daemon that is shutting down to release the
 // state lock before refusing to start.
 const LOCK_WAIT_MS = 2000;
@@ -2037,6 +2059,10 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
           return connection;
         },
         closeConnection: detachConnection,
+        log: opts.log ?? makeNonBlockingLog(STDERR_FD),
+        now: opts.listen.now ?? Date.now,
+        refusalLogIntervalMs: opts.listen.refusalLogIntervalMs ?? REFUSAL_LOG_INTERVAL_MS,
+        maxRefusalWindows: opts.listen.maxRefusalWindows ?? MAX_REFUSAL_WINDOWS,
       });
     } catch (error) {
       await releaseResources();

package/src/daemon/format-log-field.ts

@@ -0,0 +1,38 @@
+// The most characters of a field a log line keeps; a longer one is cut and
+// ends in `...`.
+const MAX_FIELD_CHARS = 64;
+
+/**
+ * Formats a value for one `key=value` field of a log line. Every character
+ * outside printable ASCII, and a space, `"`, `=`, or `\`, is written as a
+ * `\u{hex}` escape, so a value from the network can neither move the
+ * terminal, start a new line, nor forge another field. The value is cut to
+ * 64 characters before it is escaped.
+ */
+export function formatLogField(value: string): string {
+  let formatted = '';
+  let kept = 0;
+
+  // Iterating a string steps by code point, so a character outside the
+  // basic plane counts and escapes as one.
+  for (const char of value) {
+    if (kept === MAX_FIELD_CHARS) {
+      return `${formatted}...`;
+    }
+
+    formatted += isPlainChar(char) ? char : formatEscape(char);
+    kept++;
+  }
+
+  return formatted;
+}
+
+function isPlainChar(char: string): boolean {
+  const code = char.codePointAt(0) ?? 0;
+
+  return code > 0x20 && code < 0x7f && char !== '"' && char !== '=' && char !== '\\';
+}
+
+function formatEscape(char: string): string {
+  return `\\u{${(char.codePointAt(0) ?? 0).toString(16)}}`;
+}

package/src/daemon/make-non-blocking-log.ts

@@ -0,0 +1,91 @@
+import { write } from 'node:fs';
+import { promisify } from 'node:util';
+
+// The most bytes of lines that wait behind the write in flight; a line past
+// it is dropped and counted.
+const MAX_QUEUED_BYTES = 64 * 1024;
+
+// The node:fs write without a callback, which Bun runs on its thread pool.
+const writeAsync = promisify(write);
+
+/**
+ * Makes a log that writes each line to a file descriptor without ever
+ * blocking the event loop, so a reader that stops reading stalls nothing
+ * but the log. Each write goes through the asynchronous node:fs write,
+ * which Bun runs on its thread pool, one write at a time. Lines that
+ * arrive meanwhile queue up to 64 KiB; a line past that is dropped, and the
+ * next write after the drops starts with one `atc log dropped=N` line. A
+ * failed write drops its lines and counts them the same way, and the next
+ * line logged writes again.
+ */
+export function makeNonBlockingLog(fd: number): (line: string) => void {
+  let queue: string[] = [];
+  let queuedBytes = 0;
+  let dropped = 0;
+  let writing = false;
+
+  const recordLine = (line: string): boolean => {
+    const text = `${line}\n`;
+    const bytes = Buffer.byteLength(text);
+
+    if (queuedBytes + bytes > MAX_QUEUED_BYTES) {
+      return false;
+    }
+
+    queue.push(text);
+
+    queuedBytes += bytes;
+
+    return true;
+  };
+
+  const writeNext = (): void => {
+    if (queue.length === 0 && dropped === 0) {
+      writing = false;
+
+      return;
+    }
+
+    writing = true;
+
+    const lines = dropped > 0 ? [`atc log dropped=${String(dropped)}\n`, ...queue] : queue;
+
+    // The lines this write stands for, the ones the dropped line counts
+    // included, which a failed write drops again.
+    const count = dropped + queue.length;
+
+    queue = [];
+    queuedBytes = 0;
+    dropped = 0;
+    void writeChunk(Buffer.from(lines.join('')), count);
+  };
+
+  const writeChunk = async (chunk: Buffer, lineCount: number): Promise<void> => {
+    let rest = chunk;
+
+    try {
+      while (rest.length > 0) {
+        const result = await writeAsync(fd, rest);
+
+        rest = rest.subarray(result.bytesWritten);
+      }
+    } catch {
+      dropped += lineCount;
+      writing = false;
+
+      return;
+    }
+
+    writeNext();
+  };
+
+  return (line) => {
+    if (!recordLine(line)) {
+      dropped++;
+    }
+
+    if (!writing) {
+      writeNext();
+    }
+  };
+}

package/src/daemon/refusal-log.ts

@@ -0,0 +1,163 @@
+import { formatLogField } from './format-log-field';
+
+// Why the TCP listener refused a handshake: a missing token, a wrong one, a
+// handshake that would wait while the cap of delayed handshakes is full, a
+// socket that closed while its handshake waited, a line other than one
+// handshake before the handshake passed, or a line over the size cap
+// before it passed.
+type HandshakeRefusalReason =
+  | 'missing_token'
+  | 'unauthorized'
+  | 'delay_cap_full'
+  | 'closed_during_delay'
+  | 'unexpected_line'
+  | 'line_too_long';
+
+export type Refusal =
+  | {
+      readonly event: 'handshake_refused';
+      readonly peer: string;
+      readonly reason: HandshakeRefusalReason;
+    }
+  | {
+      readonly event: 'principal_refused';
+      readonly peer: string;
+    };
+
+interface RefusalLogOptions {
+  readonly log: (line: string) => void;
+  readonly now: () => number;
+
+  // How long a window of repeated refusals lasts before the next one is
+  // logged again.
+  readonly intervalMs: number;
+
+  // How many windows are tracked at once; a refusal that would start one
+  // past the cap counts toward one overflow window instead.
+  readonly maxWindows: number;
+}
+
+interface RefusalWindow {
+  readonly startedAt: number;
+
+  // The refusals in the window after the first, which no line holds yet.
+  pending: number;
+}
+
+// The line of the window that counts refusals past the cap of windows.
+const OVERFLOW_LINE = 'atc tcp event=refused peer=overflow';
+
+/**
+ * Logs TCP listener refusals as `key=value` lines, at most one per window
+ * for each peer and kind of refusal: a handshake refusal per reason, and a
+ * principal refusal, which never holds the principal it gave. The first
+ * refusal of a window logs at once with `count=1`; later ones in the window
+ * are counted, and a line with their `count` follows once the window ends,
+ * so the counts of every line sum to every refusal. While the cap of
+ * windows is full, a refusal that would start a new window counts toward
+ * one overflow window with `peer=overflow` instead, so a flood across many
+ * peers logs no more lines than the cap allows. Ended windows are logged on
+ * the next refusal from any peer and on a drain.
+ */
+export class RefusalLog {
+  private readonly opts: RefusalLogOptions;
+
+  // Keyed by the line without its count, in the order the windows started.
+  private readonly windows = new Map<string, RefusalWindow>();
+
+  private overflow: RefusalWindow | null = null;
+
+  constructor(opts: RefusalLogOptions) {
+    this.opts = opts;
+  }
+
+  record(refusal: Refusal): void {
+    const now = this.opts.now();
+
+    this.drainEnded(now);
+
+    const line = formatRefusal(refusal);
+    const window = this.windows.get(line);
+
+    if (window !== undefined) {
+      window.pending++;
+
+      return;
+    }
+
+    if (this.windows.size >= this.opts.maxWindows) {
+      this.recordOverflow(now);
+
+      return;
+    }
+
+    this.windows.set(line, { startedAt: now, pending: 0 });
+    this.opts.log(`${line} count=1`);
+  }
+
+  /**
+   * Logs the pending count of every window and forgets them all.
+   */
+  drain(): void {
+    for (const [line, window] of this.windows) {
+      this.logPending(line, window);
+    }
+
+    this.windows.clear();
+
+    if (this.overflow !== null) {
+      this.logPending(OVERFLOW_LINE, this.overflow);
+
+      this.overflow = null;
+    }
+  }
+
+  // Windows start in map order and all last the same interval, so the
+  // ended ones lead the map.
+  private drainEnded(now: number): void {
+    if (this.overflow !== null && this.hasEnded(this.overflow, now)) {
+      this.logPending(OVERFLOW_LINE, this.overflow);
+
+      this.overflow = null;
+    }
+
+    for (const [line, window] of this.windows) {
+      if (!this.hasEnded(window, now)) {
+        return;
+      }
+
+      this.windows.delete(line);
+      this.logPending(line, window);
+    }
+  }
+
+  private hasEnded(window: Readonly<RefusalWindow>, now: number): boolean {
+    return now - window.startedAt >= this.opts.intervalMs;
+  }
+
+  private logPending(line: string, window: Readonly<RefusalWindow>): void {
+    if (window.pending > 0) {
+      this.opts.log(`${line} count=${window.pending}`);
+    }
+  }
+
+  private recordOverflow(now: number): void {
+    if (this.overflow !== null) {
+      this.overflow.pending++;
+
+      return;
+    }
+
+    this.overflow = { startedAt: now, pending: 0 };
+
+    this.opts.log(`${OVERFLOW_LINE} count=1`);
+  }
+}
+
+function formatRefusal(refusal: Refusal): string {
+  const peer = formatLogField(refusal.peer);
+
+  return refusal.event === 'handshake_refused'
+    ? `atc tcp event=handshake_refused peer=${peer} reason=${refusal.reason}`
+    : `atc tcp event=principal_refused peer=${peer} principal=unlisted`;
+}

package/src/daemon/restore-fleet.ts

@@ -209,6 +209,7 @@ const REFUSED_ADOPT_CODES: ReadonlySet<string> = new Set([
   'auth_blocked',
   'auth_binding_invalid',
   'broker_not_ready',
+  'auth_placeholder_unsupported',
 ]);
 
 async function tryAdoptTerminal(

package/src/daemon/start-tcp-listener.ts

@@ -1,6 +1,8 @@
 import type { DaemonConnection, TCPPeer } from './daemon-connection';
 import { findTokenFingerprint } from './find-token-fingerprint';
+import { formatLogField } from './format-log-field';
 import { HandshakeThrottle } from './handshake-throttle';
+import { RefusalLog } from './refusal-log';
 
 // The slice of an accepted socket a protocol connection writes to and ends.
 interface ListenerSocket {
@@ -26,6 +28,16 @@ interface TCPListenerOptions {
 
   // oxlint-disable-next-line prefer-readonly-parameter-types -- a connection is a live object the daemon releases
   readonly closeConnection: (connection: DaemonConnection) => void;
+
+  // Where the listener start and each refusal are logged, one line at a
+  // time, with the clock and the window that summarize repeated refusals
+  // from one peer.
+  readonly log: (line: string) => void;
+  readonly now: () => number;
+  readonly refusalLogIntervalMs: number;
+
+  // How many peers and kinds of refusal the refusal log tracks at once.
+  readonly maxRefusalWindows: number;
 }
 
 export interface TCPListener {
@@ -55,6 +67,13 @@ export function startTCPListener(opts: TCPListenerOptions): TCPListener {
   const throttle = new HandshakeThrottle(opts.failureDelayMs);
   const connections = new Set<DaemonConnection>();
 
+  const refusals = new RefusalLog({
+    log: opts.log,
+    now: opts.now,
+    intervalMs: opts.refusalLogIntervalMs,
+    maxWindows: opts.maxRefusalWindows,
+  });
+
   let delayed = 0;
 
   // Ends the delayed handshake of each open socket once it closes.
@@ -77,6 +96,12 @@ export function startTCPListener(opts: TCPListenerOptions): TCPListener {
             if (delay > 0 && delayed >= opts.maxDelayedHandshakes) {
               throttle.recordFailure(address, Date.now());
 
+              refusals.record({
+                event: 'handshake_refused',
+                peer: address,
+                reason: 'delay_cap_full',
+              });
+
               return null;
             }
 
@@ -96,6 +121,12 @@ export function startTCPListener(opts: TCPListenerOptions): TCPListener {
               delayed--;
 
               if (waited === 'closed') {
+                refusals.record({
+                  event: 'handshake_refused',
+                  peer: address,
+                  reason: 'closed_during_delay',
+                });
+
                 return null;
               }
             }
@@ -107,12 +138,22 @@ export function startTCPListener(opts: TCPListenerOptions): TCPListener {
 
             if (fingerprint === null) {
               throttle.recordFailure(address, Date.now());
+
+              refusals.record({
+                event: 'handshake_refused',
+                peer: address,
+                reason: presented === null ? 'missing_token' : 'unauthorized',
+              });
             }
 
             return fingerprint;
           },
-          recordFailure: () => {
+          recordFailure: (reason) => {
             throttle.recordFailure(address, Date.now());
+            refusals.record({ event: 'handshake_refused', peer: address, reason });
+          },
+          recordRefusedPrincipal: () => {
+            refusals.record({ event: 'principal_refused', peer: address });
           },
         };
 
@@ -136,6 +177,10 @@ export function startTCPListener(opts: TCPListenerOptions): TCPListener {
     },
   });
 
+  opts.log(
+    `atc tcp event=listening host=${formatLogField(server.hostname)} port=${String(server.port)}`,
+  );
+
   return {
     port: server.port,
     setTokens(next) {
@@ -160,6 +205,7 @@ export function startTCPListener(opts: TCPListenerOptions): TCPListener {
       }
 
       server.stop(true);
+      refusals.drain();
     },
   };
 }

package/src/protocol/protocol.ts

@@ -65,6 +65,7 @@ const ERROR_CODES = [
   'auth_binding_invalid',
   'auth_revocation_pending',
   'broker_not_ready',
+  'auth_placeholder_unsupported',
   'host_leased',
   'confirmation_required',
   'confirm_token_invalid',