@crvouga/dev-fleet 0.1.0 → 0.3.0

package/src/platform/resource-verify.ts

@@ -3,7 +3,11 @@ import type { Check, Runner } from '../types';
 
 const AGENT_DROP_IN =
   '/etc/systemd/user/t3code-.scope.d/60-personal-fleet.conf';
-const GUARDS = ['systemd-oomd.service', 'personal-fleet-disk-guard.service'];
+const GUARDS = [
+  'systemd-oomd.service',
+  'personal-fleet-disk-guard.service',
+  'personal-fleet-disk-gc.timer',
+];
 const MIB = 1024 * 1024;
 const FLOOR_MIB = policy.resourceSafety.diskGuardFloorMiB;
 
@@ -67,7 +71,7 @@ const diskAboveFloor =
     if (free >= FLOOR_MIB * MIB) return undefined;
     return [
       'DISK_FREE_BELOW_FLOOR',
-      `${path} has ${Math.floor(free / MIB)} MiB free, under the ${FLOOR_MIB} MiB floor. The guard stops runaway writers but never deletes files; remove stale worktrees or data.`,
+      `${path} has ${Math.floor(free / MIB)} MiB free, under the ${FLOOR_MIB} MiB floor. The disk GC already removed idle build output and caches; remove stale worktrees or data, or run "sudo systemctl start personal-fleet-disk-gc.service" and read its journal.`,
     ];
   };
 
@@ -90,7 +94,7 @@ const tmpWritable: Probe = async (run) =>
 
 /** Measured memory and disk safety on an Ubuntu worker: the running managers,
  * not the files Ansible wrote. Free space below the guard floor fails because
- * the guard only stops runaway writers; a person must recover space.
+ * what is left after the disk GC is work a person must decide about.
  */
 export async function verifyResourceSafety(
   home: string,
@@ -122,7 +126,7 @@ export async function verifyResourceSafety(
       id: 'ubuntu:resource-safety',
       status: 'pass',
       summary:
-        'systemd-oomd and the disk guard are running, user workloads are capped below physical memory, T3 agents have per-agent limits, swap is active, free disk is above the guard floor and /tmp is writable.',
+        'systemd-oomd, the disk guard and the disk GC timer are running, user workloads are capped below physical memory, T3 agents have per-agent limits, swap is active, free disk is above the guard floor and /tmp is writable.',
     },
   ];
 }

package/src/platform/t3-policy.ts

@@ -1,6 +1,8 @@
 import { runAnsible } from './ansible';
 import { desired } from '../t3/desired';
 import policy from '../../ansible/ubuntu/t3/policy.json';
+import ubuntu from '../../ansible/ubuntu/policy.json';
+import { restartDeferral } from './t3-service';
 import { basename, dirname, join, resolve } from 'node:path';
 import { rename, rm, symlink } from 'node:fs/promises';
 import { userInfo } from 'node:os';
@@ -34,6 +36,7 @@ export async function stageT3Policy(
       t3_policy_document: document,
       development_user: user.username,
       development_uid: user.uid,
+      development_home: user.homedir,
     }),
     timeoutMs: 120_000,
   });
@@ -84,14 +87,21 @@ export const T3_RESTARTED_SUMMARY =
   'T3 was restarted to load the new managed policy; the running server confirms it.';
 
 /** `t3-policy.yml` restarts a running T3 that has not loaded the staged policy
- * (ending its running turns), so every node offers the same providers after
- * every sync. This measures the outcome; `restarted` says whether the app
- * restarted during this sync and so needs time to reconnect.
+ * so every node offers the same providers, but only while it runs no agent
+ * turn: a busy T3 keeps its turns and the play records the restart as
+ * pending, for personal-worker-recovery to apply at the first idle check.
+ * This measures the outcome; `restarted` says whether the app restarted
+ * during this sync and so needs time to reconnect.
  */
 export async function loadedT3Policy(
   executable: string,
   run: Runner,
-  options: { restarted: boolean; pause?: () => Promise<void> }
+  options: {
+    restarted: boolean;
+    pause?: () => Promise<void>;
+    uid?: number;
+    now?: number;
+  }
 ): Promise<Check> {
   // A restarted desktop app takes a few seconds to come back with its server.
   const check = await verifyT3Policy(
@@ -103,8 +113,25 @@ export async function loadedT3Policy(
           setTimeout(done, options.restarted ? 5000 : 1000)
         ))
   );
-  if (check.status !== 'pass')
-    return { ...check, summary: 'T3_POLICY_RESTART_FAILED' };
+  if (check.status !== 'pass') {
+    const deferral = await restartDeferral(
+      run,
+      options.uid ?? userInfo().uid,
+      options.now
+    );
+    if (!deferral.pending)
+      return { ...check, summary: 'T3_POLICY_RESTART_FAILED' };
+    return {
+      ...check,
+      status: deferral.overdue ? 'fail' : 'warn',
+      summary: 'T3_POLICY_RESTART_PENDING',
+      remedy: {
+        action: deferral.overdue
+          ? `Agent turns kept T3 from loading the staged policy for ${ubuntu.t3RestartMaxDeferralHours} hours. Finish or stop them, or restart t3code-desktop.service on the worker (this ends its running turns).`
+          : 'Agent turns are running, so T3 keeps them and loads the staged policy at the first check of personal-worker-recovery with no turn running.',
+      },
+    };
+  }
   return options.restarted
     ? { ...check, summary: T3_RESTARTED_SUMMARY }
     : check;

package/src/platform/t3-service.ts

@@ -1,3 +1,4 @@
+import policy from '../../ansible/ubuntu/policy.json';
 import type { Runner, Check } from '../types';
 
 /** The user unit that runs the pinned desktop app (UI and embedded server). */
@@ -44,6 +45,109 @@ export async function convergeT3Service(
   ];
 }
 
+/** The recovery script, installed outside every revision (`tasks/recovery.yml`). */
+export const T3_HEALTH_SCRIPT = '/usr/local/lib/personal-fleet/t3-health.sh';
+
+/** The record of the package the desktop app was unpacked from
+ * (`t3-desktop.yml`): `T3-Code-<version>-<arch>.deb`. */
+export const T3_DESKTOP_RELEASE =
+  '/opt/T3 Code (Nightly)/.personal-fleet-version';
+
+/** Where a play records a T3 restart it deferred because agent turns were
+ * running (`tasks/t3-restart.yml`): the second it was first deferred.
+ * personal-worker-recovery clears it when it restarts the idle app. */
+export function t3RestartMarker(uid: number): string {
+  return `/run/user/${uid}/personal-t3-restart-pending`;
+}
+
+/** A restart deferred while agent turns run, and whether it has waited longer
+ * than the policy allows. */
+export async function restartDeferral(
+  run: Runner,
+  uid: number,
+  now: number = Date.now()
+): Promise<{ pending: boolean; overdue: boolean }> {
+  const marker = await run(['cat', t3RestartMarker(uid)]);
+  if (!marker.ok) return { pending: false, overdue: false };
+  const since = Number(marker.stdout.trim());
+  const limit = policy.t3RestartMaxDeferralHours * 3600;
+  return {
+    pending: true,
+    overdue: Number.isFinite(since) && now / 1000 - since > limit,
+  };
+}
+
+/** The release the running server reports, compared with the one installed.
+ * Asks the server itself, so it needs no `t3` on the search path. A new
+ * release is installed beside a running app, which restarts into it only
+ * while it runs no agent turn: until then this is T3_RESTART_PENDING, and a
+ * failure once the restart has waited longer than the policy allows. */
+export async function runningVersionCheck(
+  run: Runner,
+  uid: number,
+  now: number = Date.now()
+): Promise<Check> {
+  const server = await run(
+    [
+      'curl',
+      '--fail',
+      '--silent',
+      '--max-time',
+      '10',
+      'http://127.0.0.1:3773/.well-known/t3/environment',
+    ],
+    { timeoutMs: 15_000 }
+  );
+  const installed = await run(['cat', T3_DESKTOP_RELEASE]);
+  const running = serverVersion(server.ok ? server.stdout : '');
+  const release = /^T3-Code-(.+)-[a-z0-9]+\.deb$/.exec(
+    installed.ok ? installed.stdout.trim() : ''
+  )?.[1];
+  const id = 't3:running-version';
+  if (!running || !release)
+    return {
+      id,
+      status: 'fail',
+      summary: 'T3_RUNNING_VERSION_UNKNOWN',
+      remedy: {
+        action:
+          'The running server or the installed release could not be read. Check worker:t3-health, then rerun fleet-sync to reinstall the pinned desktop app.',
+      },
+    };
+  if (running === release)
+    return {
+      id,
+      status: 'pass',
+      summary: `The running T3 server is the installed release ${release}.`,
+    };
+  const deferral = await restartDeferral(run, uid, now);
+  return {
+    id,
+    status: deferral.overdue ? 'fail' : 'warn',
+    summary: 'T3_RESTART_PENDING',
+    remedy: {
+      action: deferral.overdue
+        ? `T3 still runs ${running} after ${policy.t3RestartMaxDeferralHours} hours because agent turns kept running. Finish or stop them, or restart ${T3_DESKTOP_UNIT} on the worker (this ends its running turns).`
+        : `T3 runs ${running}; ${release} is installed. personal-worker-recovery restarts it at the first check with no agent turn running.`,
+    },
+  };
+}
+
+function serverVersion(body: string): string | undefined {
+  try {
+    const value: unknown = JSON.parse(body);
+    const version =
+      typeof value === 'object' && value !== null
+        ? (value as Record<string, unknown>)['serverVersion']
+        : undefined;
+    return typeof version === 'string' && /^[\w.+-]+$/.test(version)
+      ? version
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** When the desktop app last started; changes exactly when it restarts. */
 export async function t3StartedAt(run: Runner): Promise<string> {
   const shown = await run([

package/src/platform/types.ts

@@ -110,10 +110,6 @@ export type Platform = {
 
   /** App-bundled Tailscale CLI binaries that exist (used when `tailscale` is not on PATH). */
   tailscaleAppBinaries(): readonly string[];
-  /** VS Code user `settings.json`, or `null` when unknown on this OS. */
-  vscodeSettingsPath(): string | null;
-  /** VS Code `code` CLI binaries shipped inside the installed app. */
-  vscodeCliBinaries(): readonly string[];
 
   /** Install (or replace) a periodic job. Never throws — returns a result. */
   installScheduledJob(job: ScheduledJob): NotifierTestResult;

package/src/platform/ubuntu-audit.ts

@@ -31,12 +31,15 @@ export async function auditUbuntu(run: Runner): Promise<UbuntuAudit> {
   }
   const version =
     /^VERSION_ID="?([0-9]+\.[0-9]+)"?$/m.exec(release.stdout)?.[1] ?? null;
-  const architecture = /^(amd64|arm64)\s*$/.exec(arch.stdout)?.[1] ?? null;
+  const reported = arch.stdout.trim();
+  const architecture = policy.architectures.includes(reported)
+    ? reported
+    : null;
   return {
     supported:
       release.ok &&
       /^ID=ubuntu$/m.test(release.stdout) &&
-      version === '26.04' &&
+      version === policy.release &&
       architecture !== null,
     release: version,
     architecture,

package/src/platform/windows.ts

@@ -110,20 +110,6 @@ export class WindowsPlatform implements Platform {
     );
   }
 
-  vscodeSettingsPath(): string | null {
-    const base =
-      process.env['APPDATA']?.trim() || join(homedir(), 'AppData/Roaming');
-    return join(base, 'Code/User/settings.json');
-  }
-
-  vscodeCliBinaries(): readonly string[] {
-    const base =
-      process.env['LOCALAPPDATA']?.trim() || join(homedir(), 'AppData/Local');
-    return [join(base, 'Programs/Microsoft VS Code/bin/code.cmd')].filter((p) =>
-      existsSync(p)
-    );
-  }
-
   installScheduledJob(job: ScheduledJob): NotifierTestResult {
     return {
       ok: false,

package/src/remote-bootstrap.ts

@@ -6,7 +6,7 @@ import { isRevision } from './machine/state';
 import { sshArgs, shellQuote, sshFailure } from './ssh';
 import type { FleetNode, NodeReport, Runner, Check } from './types';
 import { record } from './config';
-import type { FleetDefinition } from './definition';
+import { installedDefinition, type FleetDefinition } from './definition';
 import { cleanCheck, validCheck } from './protocol';
 
 export interface BootstrapPayload {
@@ -48,16 +48,10 @@ export async function prepareBootstrap(
   );
   // The fleet configuration is data, not source: it travels beside the code.
   return payload && options.definition
-    ? { ...payload, config: JSON.stringify(options.definition, null, 2) + '\n' }
+    ? { ...payload, config: installedDefinition(options.definition) }
     : payload;
 }
 
-/** Installs the approved fleet configuration where every launcher and job on
- * the node reads it. It holds no secret.
- */
-const INSTALL_CONFIG =
-  'umask 077; d="$HOME/.config/dev-fleet"; mkdir -p "$d" && cat >"$d/fleet.json.new" && mv "$d/fleet.json.new" "$d/fleet.json"';
-
 /** Workers run one revision and never need history: the bundle holds only the
  * approved commit and its files (about a quarter of the full history), and the
  * receiving checkout is marked shallow at that commit. `git bundle create`
@@ -104,17 +98,9 @@ export async function bootstrapRemote(
 ): Promise<NodeReport> {
   const cached = await cachedRevision(node, payload.revision, run);
   if (typeof cached !== 'boolean') return { node: node.id, checks: [cached] };
-  if (payload.config) {
-    const installed = await run([...sshArgs(node), INSTALL_CONFIG], {
-      input: payload.config,
-      timeoutMs: 20_000,
-    });
-    if (!installed.ok)
-      return { node: node.id, checks: [sshFailure(installed)] };
-  }
   const transfer = cached
-    ? { mode: 'cached', input: '' }
-    : { mode: 'transfer', input: payload.bundle };
+    ? { mode: 'cached', bundle: '' }
+    : { mode: 'transfer', bundle: payload.bundle };
   const command = [
     'sh',
     '-c',
@@ -128,7 +114,7 @@ export async function bootstrapRemote(
     .map(shellQuote)
     .join(' ');
   const result = await run([...sshArgs(node), command], {
-    input: transfer.input,
+    input: bootstrapInput(payload.config, transfer.bundle),
     timeoutMs: 5_400_000,
   });
   const evidence = parseEvidence(result);
@@ -150,6 +136,18 @@ export async function bootstrapRemote(
   };
 }
 
+/** What the bootstrap reads on stdin: one line with the fleet configuration
+ * (installed under the remote lock, so overlapping runs never both write it),
+ * then the bundle when the worker lacks the revision.
+ */
+export function bootstrapInput(
+  config: string | undefined,
+  bundle: string
+): string {
+  const line = config ? Buffer.from(config).toString('base64') : '';
+  return `${line}\n${bundle}`;
+}
+
 async function cachedRevision(
   node: FleetNode,
   revision: string,

package/src/remote-entry.ts

@@ -6,6 +6,8 @@ import { syncWorkspace } from './sync';
 import { repairWorkspace, validRepairs } from './repair-runner';
 import { validSnapshot } from './protocol';
 import type { Fingerprint } from './types';
+import { machineProviders } from './t3/providers';
+import { accountContext, nodeAccountChecks } from './accounts/context';
 
 async function main(): Promise<void> {
   const raw: unknown = JSON.parse(
@@ -36,6 +38,16 @@ async function main(): Promise<void> {
       raw['expected'] as Fingerprint
     );
     process.stdout.write(JSON.stringify({ version: 1, checks }));
+  } else if (raw['action'] === 'accounts') {
+    // The fast account path: only the account-derived T3 instances. T3
+    // watches its settings, so no restart and no running turn ends.
+    if (raw['apply'] !== true)
+      throw new Error('Account propagation requires explicit authorization.');
+    const checks = [
+      await machineProviders(node.id, node.workspace, true),
+      ...(await nodeAccountChecks(await accountContext())),
+    ];
+    process.stdout.write(JSON.stringify({ version: 1, checks }));
   } else if (raw['action'] === 'sync') {
     if (raw['apply'] !== true)
       throw new Error('Sync requires explicit authorization.');
@@ -84,6 +96,8 @@ async function configureRequest(
 function validRequest(raw: unknown): raw is Record<string, unknown> {
   return (
     record(raw) &&
-    ['probe', 'sync', 'repair', 'configure'].includes(String(raw['action']))
+    ['probe', 'sync', 'repair', 'configure', 'accounts'].includes(
+      String(raw['action'])
+    )
   );
 }

package/src/repair-catalog.ts

@@ -47,7 +47,7 @@ export const REPAIR_RECIPES: RepairRecipe[] = [
     owner: 'dev-fleet',
     automatic: true,
     action:
-      'Links ~/.local/bin/devfleet to this checkout. Nothing is copied and no configuration is changed.',
+      'Links ~/.local/bin/devfleet to this checkout of dev-fleet (refused for an installed package, which is not one). Nothing is copied and no configuration is changed.',
     commands: [['sh', 'bootstrap/install-launcher.sh']],
   },
   {

package/src/runner.ts

@@ -24,7 +24,7 @@ export function runCommand(
     const child = spawn(command[0]!, command.slice(1), {
       cwd: options.cwd,
       env: {
-        ...process.env,
+        ...(options.isolatedEnv ? {} : process.env),
         ...options.env,
         GIT_TERMINAL_PROMPT: '0',
         CI: '1',

package/src/service-auth.ts

@@ -42,6 +42,18 @@ export async function codingAuth(
   ];
 }
 
+/** CLIs with no sign-in of their own to check, and why. Each says where
+ * its access is proven instead; none is a silent skip.
+ */
+export const PROXY_ROUTED: Record<string, string> = {
+  gemini:
+    'gemini signs in through the CLI proxy and has no T3 launcher; provider:gemini:inference proves its route from this node.',
+  copilot:
+    'copilot is not routed through the CLI proxy and dev-fleet does not manage its GitHub sign-in; no provider account is checked.',
+  opencode:
+    'opencode signs in through the CLI proxy; agent:muse:session and the per-account agent:opencode sessions prove it from this node.',
+};
+
 export async function serviceAuth(run: Runner): Promise<Check[]> {
   const services: Service[] = [
     {
@@ -89,14 +101,12 @@ export async function serviceAuth(run: Runner): Promise<Check[]> {
   ];
   const checks: Check[] = [];
   for (const service of services) checks.push(await serviceCheck(service, run));
-  for (const id of ['gemini', 'copilot', 'opencode'])
+  for (const [id, reason] of Object.entries(PROXY_ROUTED))
     checks.push({
       id: `auth:${id}`,
       status: 'skip',
-      summary: `${id} provider authorization has no verified noninteractive status adapter in this CLI. Installed binaries or saved keys are not proof of access.`,
-      remedy: {
-        action: `Verify ${id} provider access locally using its supported account diagnostics. No prompt or billable request was made.`,
-      },
+      required: false,
+      summary: `AUTH_NOT_SUPPORTED_ON_ROUTE: ${reason}`,
     });
   return checks;
 }

package/src/state/bucket.ts

@@ -0,0 +1,208 @@
+import { randomUUID } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
+import { record } from '../config';
+import { FleetUsageError } from '../errors';
+
+/** Where the fleet's state is kept for good. An S3-compatible bucket (AWS S3,
+ * Cloudflare R2, Backblaze B2, MinIO) is the usual one; a directory on an
+ * attached disk or a mounted share works the same way.
+ */
+export type Bucket =
+  | {
+      kind: 's3';
+      bucket: string;
+      /** Omitted for AWS S3 itself. */
+      endpoint?: string;
+      region?: string;
+      /** Key prefix, so one bucket can hold more than this fleet's state. */
+      prefix: string;
+      /** Omitted to use the standard AWS environment or profile. */
+      accessKeyId?: string;
+      secretAccessKey?: string;
+    }
+  | { kind: 'directory'; path: string };
+
+export const DEFAULT_PREFIX = 'dev-fleet';
+
+const text = (value: unknown, pattern: RegExp): value is string =>
+  typeof value === 'string' && pattern.test(value);
+
+const ENDPOINT =
+  /^(https:\/\/[A-Za-z0-9.-]{1,253}(:\d{1,5})?|http:\/\/(127\.0\.0\.1|localhost)(:\d{1,5})?)$/;
+const KEY = /^[\x21-\x7e]{1,512}$/;
+
+function invalid(reason: string): never {
+  throw new FleetUsageError(`Invalid bucket settings: ${reason}`);
+}
+
+function directory(value: Record<string, unknown>): Bucket {
+  if (Object.keys(value).some((key) => !['version', 'directory'].includes(key)))
+    invalid('a directory takes no other setting.');
+  const path = value['directory'];
+  if (!text(path, /^\/[^\x00-\x1f\x7f]{1,4000}$/))
+    invalid('directory must be an absolute path.');
+  return { kind: 'directory', path };
+}
+
+function prefix(value: unknown): string {
+  if (value === undefined) return DEFAULT_PREFIX;
+  if (
+    !text(value, /^[A-Za-z0-9][A-Za-z0-9._/-]{0,199}$/) ||
+    value.includes('..') ||
+    value.endsWith('/')
+  )
+    invalid('prefix must be a plain key prefix such as dev-fleet.');
+  return value;
+}
+
+function credentials(
+  value: Record<string, unknown>
+): { accessKeyId: string; secretAccessKey: string } | Record<string, never> {
+  const { accessKeyId, secretAccessKey } = value;
+  if (accessKeyId === undefined && secretAccessKey === undefined) return {};
+  if (!text(accessKeyId, KEY) || !text(secretAccessKey, KEY))
+    invalid('accessKeyId and secretAccessKey must be given together.');
+  return { accessKeyId, secretAccessKey };
+}
+
+const S3_SETTINGS = [
+  'version',
+  'bucket',
+  'endpoint',
+  'region',
+  'prefix',
+  'accessKeyId',
+  'secretAccessKey',
+];
+
+function s3(value: Record<string, unknown>): Bucket {
+  if (Object.keys(value).some((key) => !S3_SETTINGS.includes(key)))
+    invalid('unknown setting.');
+  const { bucket, endpoint, region } = value;
+  if (!text(bucket, /^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/))
+    invalid('bucket must be a bucket name.');
+  if (endpoint !== undefined && !text(endpoint, ENDPOINT))
+    invalid('endpoint must be an https:// origin without a path.');
+  if (region !== undefined && !text(region, /^[a-z0-9-]{1,32}$/))
+    invalid('region must be a region name such as auto or us-east-1.');
+  return {
+    kind: 's3',
+    bucket,
+    ...(endpoint ? { endpoint } : {}),
+    ...(region ? { region } : {}),
+    prefix: prefix(value['prefix']),
+    ...credentials(value),
+  };
+}
+
+/** The contents of bucket.json, or the same fields from `fleet-state --init`. */
+export function parseBucket(value: unknown): Bucket {
+  if (!record(value)) return invalid('expected a JSON object.');
+  if (value['version'] !== undefined && value['version'] !== 1)
+    invalid('unsupported version.');
+  return value['directory'] !== undefined ? directory(value) : s3(value);
+}
+
+/** The environment a devfleet command takes the bucket's credentials from. */
+export const ACCESS_KEY_ID_ENV = 'DEVFLEET_BUCKET_ACCESS_KEY_ID';
+export const SECRET_ACCESS_KEY_ENV = 'DEVFLEET_BUCKET_SECRET_ACCESS_KEY';
+
+/** Where a fleet configuration says its state is kept: a bucket's location
+ * without credentials, which never belong in a file kept in Git.
+ */
+export type BucketLocation =
+  | { bucket: string; endpoint?: string; region?: string; prefix?: string }
+  | { directory: string };
+
+const LOCATION = ['bucket', 'endpoint', 'region', 'prefix', 'directory'];
+
+/** The `state` block of a fleet configuration. */
+export function parseLocation(value: unknown): Bucket {
+  if (!record(value)) return invalid('expected a JSON object.');
+  if ('accessKeyId' in value || 'secretAccessKey' in value)
+    invalid(
+      `credentials do not belong in the fleet configuration. Set ${ACCESS_KEY_ID_ENV} and ${SECRET_ACCESS_KEY_ENV} instead.`
+    );
+  if (Object.keys(value).some((key) => !LOCATION.includes(key)))
+    invalid('unknown setting.');
+  return parseBucket(value);
+}
+
+type S3Bucket = Extract<Bucket, { kind: 's3' }>;
+
+/** The same bucket, reached with these credentials instead of its own. */
+export function withCredentials(
+  bucket: S3Bucket,
+  given: { accessKeyId?: string; secretAccessKey?: string }
+): S3Bucket {
+  const { accessKeyId: _id, secretAccessKey: _secret, ...place } = bucket;
+  return { ...place, ...credentials(given) };
+}
+
+/** Null when this machine has no bucket. The file holds credentials, so one
+ * that other users can read is refused rather than used.
+ */
+export function readBucket(path: string): Bucket | null {
+  if (!existsSync(path)) return null;
+  if (process.platform !== 'win32' && (statSync(path).mode & 0o077) !== 0)
+    throw new FleetUsageError(
+      `${path} holds bucket credentials and must be private. Run chmod 600 on it.`
+    );
+  let value: unknown;
+  try {
+    value = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return invalid('the file is not JSON.');
+  }
+  return parseBucket(value);
+}
+
+export function writeBucket(path: string, bucket: Bucket): void {
+  const { kind, ...settings } = bucket;
+  const body =
+    kind === 'directory'
+      ? { version: 1, directory: bucket.path }
+      : { version: 1, ...settings };
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, JSON.stringify(body, null, 2) + '\n', {
+      mode: 0o600,
+      flag: 'wx',
+    });
+    renameSync(temporary, path);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+/** What a report may say about the bucket: never a credential. */
+export function describeBucket(bucket: Bucket | null): Record<string, unknown> {
+  if (!bucket) return { configured: false };
+  if (bucket.kind === 'directory')
+    return { configured: true, kind: 'directory', directory: bucket.path };
+  return {
+    configured: true,
+    kind: 's3',
+    bucket: bucket.bucket,
+    ...(bucket.endpoint ? { endpoint: bucket.endpoint } : {}),
+    ...(bucket.region ? { region: bucket.region } : {}),
+    prefix: bucket.prefix,
+  };
+}
+
+/** The same target replicates the same database; a different one starts over. */
+export function bucketIdentity(bucket: Bucket): string {
+  return bucket.kind === 'directory'
+    ? `directory:${bucket.path}`
+    : `s3:${bucket.endpoint ?? 'aws'}/${bucket.bucket}/${bucket.prefix}`;
+}