@zgeoff/atc 0.1.12 → 1.0.0

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

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+import { buildOptionalBoolean } from '../shared/build-optional-boolean';
+import { buildOptionalString } from '../shared/build-optional-string';
+import { toAgentSessionID } from '../shared/to-agent-session-id';
+import { toSessionID } from '../shared/to-session-id';
+
+const EJECT_DEFAULT_PROMPT =
+  'Continue the task autonomously. Verify your work as you go and stop when it is complete.';
+
+// The `session` field every wire schema below carries: absent or
+// wrong-typed falls back to an empty string instead of failing the parse.
+// This is the one point where a session id arriving off the wire is typed
+// as the branded atc session id every daemon-side session lookup expects.
+const SESSION_DEFAULTED = z.object({
+  session: buildDefaultedString('').transform(toSessionID),
+});
+
+export const REQUEST_PARAM_SCHEMAS = {
+  'daemon.hello': z.object({
+    client: buildDefaultedString('unknown client'),
+  }),
+  'daemon.ping': z.object({}),
+  'daemon.quit': z.object({}),
+  'session.list': z.object({}),
+  'dirs.list': z.object({}),
+  'fleet.list': z.object({}),
+  'fleet.restore': z.object({
+    cols: buildDefaultedNumber(80),
+    rows: buildDefaultedNumber(24),
+  }),
+  'session.spawn': z.object({
+    cwd: z.string({ error: 'session.spawn requires a cwd' }).min(1, 'session.spawn requires a cwd'),
+    name: buildDefaultedString(''),
+    prompt: buildDefaultedString(''),
+    cols: buildDefaultedNumber(80),
+    rows: buildDefaultedNumber(24),
+
+    resume: buildDefaultedBooleanOrString(false).transform((v) =>
+      typeof v === 'string' ? toAgentSessionID(v) : v,
+    ),
+    agent: z
+      .string({ error: 'session.spawn agent must be a non-empty agent id' })
+      .min(1, 'session.spawn agent must be a non-empty agent id')
+      .optional(),
+  }),
+  'session.kill': SESSION_DEFAULTED,
+  'session.ack': SESSION_DEFAULTED,
+  'session.update': SESSION_DEFAULTED.extend({
+    name: buildOptionalString(),
+    pinned: buildOptionalBoolean(),
+  }),
+  'session.attach': SESSION_DEFAULTED.extend({
+    cols: buildDefaultedNumber(80),
+    rows: buildDefaultedNumber(24),
+  }),
+  'session.detach': SESSION_DEFAULTED,
+  'session.input': SESSION_DEFAULTED.extend({
+    d: buildDefaultedString(''),
+  }),
+  'session.resize': SESSION_DEFAULTED.extend({
+    cols: buildDefaultedNumber(0),
+    rows: buildDefaultedNumber(0),
+  }).refine((v) => v.cols >= 1 && v.rows >= 1, {
+    message: 'session.resize requires positive cols and rows',
+  }),
+  'session.resumeCommand': SESSION_DEFAULTED,
+  'session.eject': SESSION_DEFAULTED.extend({
+    prompt: buildDefaultedNonEmptyString(EJECT_DEFAULT_PROMPT),
+  }),
+  'session.adopt': SESSION_DEFAULTED.extend({
+    cols: buildDefaultedNumber(80),
+    rows: buildDefaultedNumber(24),
+  }),
+  'permission.respond': z
+    .object({
+      request: buildDefaultedString(''),
+      decision: buildDefaultedString(''),
+    })
+    .refine((v) => v.request !== '' && v.decision !== '', {
+      message: 'permission.respond requires a request and a decision',
+    }),
+} as const;
+
+function buildDefaultedString(fallback: string) {
+  return z.preprocess((v) => (typeof v === 'string' ? v : undefined), z.string().default(fallback));
+}
+
+function buildDefaultedNumber(fallback: number) {
+  return z.preprocess((v) => (typeof v === 'number' ? v : undefined), z.number().default(fallback));
+}
+
+function buildDefaultedBooleanOrString(fallback: boolean | string) {
+  return z.preprocess(
+    (v) => (typeof v === 'boolean' || typeof v === 'string' ? v : undefined),
+    z.union([z.boolean(), z.string()]).default(fallback),
+  );
+}
+
+// Absent or wrong-typed stays undefined rather than falling back to a
+// value, so the caller can tell "not given" from "given" and skip an update.
+
+// An explicit empty string also falls back to the default instead of
+// standing as a deliberate empty value.
+function buildDefaultedNonEmptyString(fallback: string) {
+  return z.preprocess(
+    (v) => (typeof v === 'string' && v !== '' ? v : undefined),
+    z.string().default(fallback),
+  );
+}

package/src/shared/agent-session-id.ts

@@ -0,0 +1,8 @@
+import type { Tagged } from 'type-fest';
+
+/**
+ * The session id an agent CLI issues for its own resume mechanism — what
+ * `claude --resume <id>` takes. Adapters mint it from a hook payload or a
+ * stored fleet row, and the fleet table keys on it.
+ */
+export type AgentSessionID = Tagged<string, 'AgentSessionID'>;

package/src/shared/build-optional-boolean.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+
+/**
+ * A boolean that tolerates anything else in its place: a non-boolean parses
+ * to undefined so the caller's default stands, rather than failing the whole
+ * object it belongs to.
+ */
+export function buildOptionalBoolean() {
+  return z.preprocess((v) => (typeof v === 'boolean' ? v : undefined), z.boolean().optional());
+}

package/src/shared/build-optional-string-array.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+
+/**
+ * A list of strings that tolerates anything else in its place. A non-array
+ * parses to undefined so the caller's default stands, and a mixed array keeps
+ * the strings in it rather than being discarded whole — a config listing one
+ * bad argument still contributes its good ones.
+ */
+export function buildOptionalStringArray() {
+  return z.preprocess(
+    (v) => (Array.isArray(v) ? v.filter((a): a is string => typeof a === 'string') : undefined),
+    z.array(z.string()).optional(),
+  );
+}

package/src/shared/build-optional-string.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+
+/**
+ * A string that tolerates anything else in its place: a non-string parses to
+ * undefined so the caller's default stands, rather than failing the whole
+ * object it belongs to.
+ */
+export function buildOptionalString() {
+  return z.preprocess((v) => (typeof v === 'string' ? v : undefined), z.string().optional());
+}

package/src/shared/collect-gateways.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+import type { AgentID } from '../agents/agent-adapter';
+import { buildOptionalStringArray } from './build-optional-string-array';
+import { isRecord } from './report';
+
+/**
+ * A Claude-compatible backend the Claude CLI is pointed at: its own agent id,
+ * its own row in the spawn menu, and its own generated settings file. The
+ * credential is never held here — a helper command supplies it at run time,
+ * so it stays out of the file atc writes.
+ */
+export interface GatewayConfig {
+  readonly id: AgentID;
+  readonly label: string;
+  readonly mark: string;
+  readonly bin: string;
+  readonly args: readonly string[];
+  readonly baseURL: string;
+  readonly apiKeyHelper?: string;
+  readonly env: Readonly<Record<string, string>>;
+}
+
+// Ids the built-in adapters answer to; a gateway may not take one.
+const BUILT_IN_IDS = new Set(['claude', 'grok', 'codex']);
+
+// One gateway map entry's keys. An absent or wrong-typed field parses to
+// undefined rather than failing the entry, so a gateway with one bad field
+// still registers with the default for it.
+const GATEWAY_ENTRY_SCHEMA = z.object({
+  label: buildOptionalNonEmptyString(),
+  mark: buildOptionalNonEmptyString(),
+  baseURL: buildOptionalNonEmptyString(),
+  bin: buildOptionalNonEmptyString(),
+  args: buildOptionalStringArray(),
+  apiKeyHelper: buildOptionalNonEmptyString(),
+  env: buildStringEnvRecord(),
+});
+
+/**
+ * Reads the gateway map into menu order. An entry without a base URL, or
+ * under an id another adapter already answers to, is left out rather than
+ * registered half-formed: every gateway in the result can be spawned.
+ */
+export function collectGateways(
+  raw: unknown,
+  claudeBin: string,
+  claudeArgs: readonly string[],
+): GatewayConfig[] {
+  if (!isRecord(raw)) {
+    return [];
+  }
+
+  const gateways: GatewayConfig[] = [];
+
+  for (const [id, entry] of Object.entries(raw)) {
+    if (id === '' || BUILT_IN_IDS.has(id)) {
+      continue;
+    }
+
+    const parsed = GATEWAY_ENTRY_SCHEMA.safeParse(entry);
+
+    if (!parsed.success || parsed.data.baseURL === undefined) {
+      continue;
+    }
+
+    const firstOfMark = (parsed.data.mark ?? id).codePointAt(0);
+
+    gateways.push({
+      id,
+      label: parsed.data.label ?? id,
+
+      // oxlint-disable-next-line no-unsafe-type-assertion -- mark falls back to id, and both are checked non-empty above, so codePointAt(0) always returns a code point
+      mark: String.fromCodePoint(firstOfMark as number),
+      bin: parsed.data.bin ?? claudeBin,
+      args: parsed.data.args ?? claudeArgs,
+      baseURL: parsed.data.baseURL,
+      ...(parsed.data.apiKeyHelper === undefined ? {} : { apiKeyHelper: parsed.data.apiKeyHelper }),
+      env: parsed.data.env,
+    });
+  }
+
+  return gateways;
+}
+
+function buildOptionalNonEmptyString() {
+  return z.preprocess(
+    (v) => (typeof v === 'string' && v !== '' ? v : undefined),
+    z.string().optional(),
+  );
+}
+
+// String values only: everything here is handed to a child process as an
+// environment variable.
+function buildStringEnvRecord() {
+  return z.preprocess(
+    (v) => {
+      if (!isRecord(v)) {
+        return {};
+      }
+
+      const env: Record<string, string> = {};
+
+      for (const [key, value] of Object.entries(v)) {
+        if (typeof value === 'string') {
+          env[key] = value;
+        }
+      }
+
+      return env;
+    },
+    z.record(z.string(), z.string()),
+  );
+}

package/src/{config.ts → shared/config.ts}

@@ -1,7 +1,11 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { isRecord } from './report';
+import { z } from 'zod';
+import { buildOptionalString } from './build-optional-string';
+import { buildOptionalStringArray } from './build-optional-string-array';
+import { collectGateways } from './collect-gateways';
+import type { GatewayConfig } from './collect-gateways';
 
 export interface Config {
   claudeBin: string;
@@ -10,6 +14,7 @@ export interface Config {
   grokArgs: string[];
   codexBin: string;
   codexArgs: string[];
+  gateways: GatewayConfig[];
   leader: LeaderKey;
 }
 
@@ -25,6 +30,7 @@ const DEFAULTS: Config = {
   grokArgs: [],
   codexBin: 'codex',
   codexArgs: [],
+  gateways: [],
   leader: { code: 0, label: '^Space' },
 };
 
@@ -38,6 +44,20 @@ export const dbFile = join(stateDir, 'atc.db');
 export const legacyFleetFile = join(stateDir, 'fleet.json');
 export const daemonPidFile = join(process.env['XDG_RUNTIME_DIR'] ?? stateDir, 'atc-daemon.pid');
 
+// A user-written config.json's top-level keys. An absent or wrong-typed
+// field parses to undefined rather than failing the file, so a bad config
+// falls back to a default instead of refusing to start atc.
+const CONFIG_SCHEMA = z.object({
+  claudeBin: buildOptionalString(),
+  claudeArgs: buildOptionalStringArray(),
+  grokBin: buildOptionalString(),
+  grokArgs: buildOptionalStringArray(),
+  codexBin: buildOptionalString(),
+  codexArgs: buildOptionalStringArray(),
+  gateways: z.unknown().optional(),
+  leader: buildOptionalString(),
+});
+
 export function loadConfig(): Config {
   mkdirSync(configDir, { recursive: true });
   mkdirSync(stateDir, { recursive: true });
@@ -51,41 +71,37 @@ export function loadConfig(): Config {
   }
 
   try {
-    const raw = readFileSync(file, 'utf8');
-    const parsed: unknown = JSON.parse(raw);
-
-    if (!isRecord(parsed)) {
-      return { ...DEFAULTS };
-    }
-
-    const claudeBin =
-      typeof parsed['claudeBin'] === 'string' ? parsed['claudeBin'] : DEFAULTS.claudeBin;
-
-    const claudeArgs = Array.isArray(parsed['claudeArgs'])
-      ? parsed['claudeArgs'].filter((a): a is string => typeof a === 'string')
-      : DEFAULTS.claudeArgs;
-
-    const grokBin = typeof parsed['grokBin'] === 'string' ? parsed['grokBin'] : DEFAULTS.grokBin;
+    return parseConfig(JSON.parse(readFileSync(file, 'utf8')));
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
 
-    const grokArgs = Array.isArray(parsed['grokArgs'])
-      ? parsed['grokArgs'].filter((a): a is string => typeof a === 'string')
-      : DEFAULTS.grokArgs;
+/**
+ * Parses a user-written config.json's already-decoded JSON value into a
+ * Config, applying every default a malformed or absent field falls back to.
+ * Total: no shape of `raw` throws, so a hand-edited config never stops atc
+ * starting.
+ */
+export function parseConfig(raw: unknown): Config {
+  const parsed = CONFIG_SCHEMA.safeParse(raw);
 
-    const codexBin =
-      typeof parsed['codexBin'] === 'string' ? parsed['codexBin'] : DEFAULTS.codexBin;
+  if (!parsed.success) {
+    return { ...DEFAULTS };
+  }
 
-    const codexArgs = Array.isArray(parsed['codexArgs'])
-      ? parsed['codexArgs'].filter((a): a is string => typeof a === 'string')
-      : DEFAULTS.codexArgs;
+  const claudeBin = parsed.data.claudeBin ?? DEFAULTS.claudeBin;
+  const claudeArgs = parsed.data.claudeArgs ?? DEFAULTS.claudeArgs;
+  const grokBin = parsed.data.grokBin ?? DEFAULTS.grokBin;
+  const grokArgs = parsed.data.grokArgs ?? DEFAULTS.grokArgs;
+  const codexBin = parsed.data.codexBin ?? DEFAULTS.codexBin;
+  const codexArgs = parsed.data.codexArgs ?? DEFAULTS.codexArgs;
+  const gateways = collectGateways(parsed.data.gateways, claudeBin, claudeArgs);
 
-    const leader =
-      (typeof parsed['leader'] === 'string' ? decodeLeader(parsed['leader']) : null) ??
-      DEFAULTS.leader;
+  const leader =
+    (parsed.data.leader === undefined ? null : decodeLeader(parsed.data.leader)) ?? DEFAULTS.leader;
 
-    return { claudeBin, claudeArgs, grokBin, grokArgs, codexBin, codexArgs, leader };
-  } catch {
-    return { ...DEFAULTS };
-  }
+  return { claudeBin, claudeArgs, grokBin, grokArgs, codexBin, codexArgs, gateways, leader };
 }
 
 // Control bytes the terminal needs for its own input: enter, tab, and esc

package/src/{get-build.ts → shared/get-build.ts}

@@ -1,6 +1,9 @@
 import { readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import pkg from '../package.json';
+import pkg from '../../package.json';
+
+// The src/ root, so the walk covers every module under it.
+const SRC_ROOT = join(import.meta.dir, '..');
 
 /**
  * The build identity used in the protocol handshake. The version alone
@@ -15,11 +18,7 @@ export function getBuild(): string {
   let stamp = 0;
 
   try {
-    for (const entry of readdirSync(import.meta.dir)) {
-      if (entry.endsWith('.ts')) {
-        stamp = Math.max(stamp, statSync(join(import.meta.dir, entry)).mtimeMs);
-      }
-    }
+    stamp = getNewestTSMtime(SRC_ROOT);
   } catch {}
 
   if (stamp === 0) {
@@ -30,3 +29,19 @@ export function getBuild(): string {
 
   return `atc/${pkg.version}+${Math.round(stamp).toString(36)}`;
 }
+
+function getNewestTSMtime(dir: string): number {
+  let stamp = 0;
+
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const entryPath = join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      stamp = Math.max(stamp, getNewestTSMtime(entryPath));
+    } else if (entry.name.endsWith('.ts')) {
+      stamp = Math.max(stamp, statSync(entryPath).mtimeMs);
+    }
+  }
+
+  return stamp;
+}

package/src/shared/get-record.ts

@@ -0,0 +1,20 @@
+import { isRecord } from './report';
+
+/**
+ * Narrows one field of a record to a record, for tests pulling a nested
+ * payload (a wire event's session descriptor, a response's session) out of
+ * loosely typed JSON. Throws rather than letting a malformed fixture pass a
+ * test vacuously.
+ */
+export function getRecord(
+  value: Readonly<Record<string, unknown>>,
+  key: string,
+): Record<string, unknown> {
+  const inner = value[key];
+
+  if (!isRecord(inner)) {
+    throw new TypeError(`${key} is not an object`);
+  }
+
+  return inner;
+}

package/src/shared/session-id.ts

@@ -0,0 +1,8 @@
+import type { Tagged } from 'type-fest';
+
+/**
+ * The atc-generated session id, minted by the session manager when it spawns
+ * or restores a session. It keys every protocol method, every daemon-side
+ * per-session map, and the hook envelope's `atcId` field.
+ */
+export type SessionID = Tagged<string, 'SessionID'>;

package/src/shared/to-agent-session-id.ts

@@ -0,0 +1,12 @@
+import type { AgentSessionID } from './agent-session-id';
+
+/**
+ * Trusts a string as an agent-issued session id. This is the one point in
+ * the codebase where a plain string becomes an `AgentSessionID`, and it adds
+ * no runtime check: the caller asserts the string is the id an agent CLI
+ * issued for its own resume mechanism.
+ */
+export function toAgentSessionID(id: string): AgentSessionID {
+  // oxlint-disable-next-line no-unsafe-type-assertion -- the one point where a string is trusted as an AgentSessionID
+  return id as AgentSessionID;
+}

package/src/shared/to-session-id.ts

@@ -0,0 +1,11 @@
+import type { SessionID } from './session-id';
+
+/**
+ * Trusts a string as an atc session id. This is the one point in the
+ * codebase where a plain string becomes a `SessionID`, and it adds no
+ * runtime check: the caller asserts the string identifies an atc session.
+ */
+export function toSessionID(id: string): SessionID {
+  // oxlint-disable-next-line no-unsafe-type-assertion -- the one point where a string is trusted as a SessionID
+  return id as SessionID;
+}

package/src/shared/to-shell-arg.ts

@@ -0,0 +1,7 @@
+/**
+ * Wraps a value in single quotes so it stands as one shell argument,
+ * escaping any single quotes the value itself contains.
+ */
+export function toShellArg(value: string): string {
+  return `'${value.replaceAll("'", String.raw`'\''`)}'`;
+}

package/src/statusline.ts

@@ -1,8 +1,8 @@
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { statusFile } from './config';
-import { isRecord, sendReport } from './report';
+import { statusFile } from './shared/config';
+import { isRecord, sendReport } from './shared/report';
 
 /**
  * Runs as the statusLine command injected into wrangled sessions. Chains the

package/src/store/bun-sqlite-driver.ts

@@ -0,0 +1,96 @@
+import type { Database, SQLQueryBindings } from 'bun:sqlite';
+import { CompiledQuery } from 'kysely';
+import type { DatabaseConnection, Driver, QueryResult } from 'kysely';
+
+/**
+ * A kysely `Driver` over one bun:sqlite handle. SQLite has a single
+ * connection, so `acquireConnection` hands it out to one caller at a time
+ * through a promise-chain mutex and `releaseConnection` lets the next
+ * caller in — the ordering every transaction (and every plain query) relies
+ * on once the store runs asynchronously.
+ */
+export class BunSqliteDriver implements Driver {
+  private readonly connection: DatabaseConnection;
+
+  private turn: Promise<void> = Promise.resolve();
+
+  private releaseTurn: () => void = () => {};
+
+  constructor(sqlite: Database) {
+    this.connection = buildConnection(sqlite);
+  }
+
+  init(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  async acquireConnection(): Promise<DatabaseConnection> {
+    const previous = this.turn;
+    let release: (() => void) | undefined;
+
+    this.turn = new Promise((resolve) => {
+      release = resolve;
+    });
+
+    await previous;
+
+    if (release !== undefined) {
+      this.releaseTurn = release;
+    }
+
+    return this.connection;
+  }
+
+  async beginTransaction(connection: DatabaseConnection): Promise<void> {
+    await connection.executeQuery(CompiledQuery.raw('begin'));
+  }
+
+  async commitTransaction(connection: DatabaseConnection): Promise<void> {
+    await connection.executeQuery(CompiledQuery.raw('commit'));
+  }
+
+  async rollbackTransaction(connection: DatabaseConnection): Promise<void> {
+    await connection.executeQuery(CompiledQuery.raw('rollback'));
+  }
+
+  releaseConnection(): Promise<void> {
+    this.releaseTurn();
+
+    return Promise.resolve();
+  }
+
+  // Waits out whatever turn is already queued before returning, so a caller
+  // that closes the underlying connection right after destroy() never does
+  // so out from under a write still in flight.
+  async destroy(): Promise<void> {
+    await this.acquireConnection();
+    await this.releaseConnection();
+  }
+}
+
+function buildConnection(sqlite: Database): DatabaseConnection {
+  return {
+    executeQuery<R>(compiledQuery: CompiledQuery): Promise<QueryResult<R>> {
+      const stmt = sqlite.query<R, SQLQueryBindings[]>(compiledQuery.sql);
+
+      // oxlint-disable-next-line no-unsafe-type-assertion -- kysely's sqlite compiler only ever binds bun:sqlite-legal values here; this is the one point where it is trusted
+      const bindings = compiledQuery.parameters as SQLQueryBindings[];
+
+      if (stmt.columnNames.length > 0) {
+        return Promise.resolve({ rows: stmt.all(...bindings) });
+      }
+
+      const result = stmt.run(...bindings);
+
+      return Promise.resolve({
+        rows: [],
+        numAffectedRows: BigInt(result.changes),
+        insertId: BigInt(result.lastInsertRowid),
+      });
+    },
+
+    streamQuery<R>(): AsyncIterableIterator<QueryResult<R>> {
+      throw new Error('BunSqliteDriver does not support streaming queries');
+    },
+  };
+}

package/src/store/fleet-entry.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { toAgentID } from '../agents/agent-adapter';
+import type { AgentID } from '../agents/agent-adapter';
+import type { AgentSessionID } from '../shared/agent-session-id';
+import { buildOptionalBoolean } from '../shared/build-optional-boolean';
+import { isRecord } from '../shared/report';
+import { toAgentSessionID } from '../shared/to-agent-session-id';
+
+export interface FleetEntry {
+  readonly name: string;
+  readonly cwd: string;
+  readonly agentSessionID: AgentSessionID;
+  readonly agent: AgentID;
+  readonly pinned?: boolean;
+  readonly lastAttachedAt?: number;
+  readonly exited?: boolean;
+}
+
+export interface FleetStore {
+  readonly loadFleet: () => Promise<FleetEntry[]>;
+  readonly writeFleet: (entries: readonly FleetEntry[]) => Promise<void>;
+}
+
+// A stored fleet row's keys. name, cwd, and the resolved agentSessionID are
+// required: a row missing any of them cannot restore a session, so the whole
+// row parses to undefined rather than a half-built entry. Fleet files
+// written before the id key was agent-neutral carry it under its Claude-era
+// name, so agentSessionID is read off whichever key the row actually has
+// before validation.
+const FLEET_ENTRY_SCHEMA = z.preprocess(
+  (value) => {
+    if (!isRecord(value)) {
+      return value;
+    }
+
+    return { ...value, agentSessionID: value['agentSessionID'] ?? value['claudeId'] };
+  },
+  z.object({
+    name: z.string(),
+    cwd: z.string(),
+    agentSessionID: z.string(),
+    agent: z.unknown().optional(),
+    pinned: buildOptionalBoolean(),
+    lastAttachedAt: buildOptionalNumber(),
+    exited: buildOptionalBoolean(),
+  }),
+);
+
+export function parseFleetEntry(raw: unknown): FleetEntry | undefined {
+  const parsed = FLEET_ENTRY_SCHEMA.safeParse(raw);
+
+  if (!parsed.success) {
+    return undefined;
+  }
+
+  return {
+    name: parsed.data.name,
+    cwd: parsed.data.cwd,
+
+    agentSessionID: toAgentSessionID(parsed.data.agentSessionID),
+    agent: toAgentID(parsed.data.agent),
+    ...(parsed.data.pinned === true ? { pinned: true } : {}),
+    ...(parsed.data.lastAttachedAt === undefined
+      ? {}
+      : { lastAttachedAt: parsed.data.lastAttachedAt }),
+    ...(parsed.data.exited === true ? { exited: true } : {}),
+  };
+}
+
+function buildOptionalNumber() {
+  return z.preprocess((v) => (typeof v === 'number' ? v : undefined), z.number().optional());
+}