@crvouga/dev-fleet 0.4.0 → 0.6.0

package/src/machine/support-matrix.ts

@@ -0,0 +1,76 @@
+import macos from '../../ansible/macos/policy.json';
+import platforms from '../../ansible/platforms.json';
+import { UBUNTU_RELEASES } from '../platform/ubuntu-release';
+
+export type SupportStatus = 'supported' | 'best effort' | 'refused';
+export interface SupportRow {
+  role: string;
+  platform: string;
+  versions: string;
+  architectures: string;
+  status: SupportStatus;
+  note: string;
+}
+
+/** Every platform and what dev-fleet does with it, from the policies the code
+ * reads: the supported rows from the macOS and Ubuntu policies, the rest from
+ * ansible/platforms.json. docs/support-matrix.md is this table. */
+export function supportMatrix(): SupportRow[] {
+  return [
+    {
+      role: 'manager',
+      platform: 'macOS',
+      versions: `${macos.minimumMajorVersion} or newer`,
+      architectures: macos.architectures.join(', '),
+      status: 'supported',
+      note: 'ansible/macos/policy.json',
+    },
+    ...UBUNTU_RELEASES.map((entry): SupportRow => ({
+      role: 'worker',
+      platform: 'Ubuntu',
+      versions: `${entry.release} (${entry.codename})`,
+      architectures: entry.architectures.join(', '),
+      status: 'supported',
+      note: 'ansible/ubuntu/policy.json; a machine of its own, physical or virtual',
+    })),
+    ...platforms.rows.map((row): SupportRow => ({
+      role: row.role,
+      platform: row.platform,
+      versions: row.versions,
+      architectures: row.architectures,
+      status: row.status as SupportStatus,
+      note: row.note,
+    })),
+  ];
+}
+
+export function renderSupportMatrix(rows = supportMatrix()): string {
+  const header = [
+    'Role',
+    'Platform',
+    'Versions',
+    'Architectures',
+    'Status',
+    'Note',
+  ];
+  const cells = rows.map((row) => [
+    row.role,
+    row.platform,
+    row.versions,
+    row.architectures,
+    row.status,
+    row.note,
+  ]);
+  const widths = header.map((title, index) =>
+    Math.max(title.length, ...cells.map((line) => line[index]!.length))
+  );
+  const line = (values: string[]) =>
+    `| ${values.map((value, index) => value.padEnd(widths[index]!)).join(' | ')} |`;
+  return [
+    line(header),
+    `| ${widths.map((width) => '-'.repeat(width)).join(' | ')} |`,
+    ...cells.map(line),
+  ].join('\n');
+}
+
+if (import.meta.main) process.stdout.write(`${renderSupportMatrix()}\n`);

package/src/manager-sync.ts

@@ -16,10 +16,9 @@ import { sshArgs, sshFailure } from './ssh';
 import type { FleetDefinition, MachineDefinition } from './definition';
 import { publicHubUrl } from './monitoring/beszel';
 import {
-  convergeable,
+  evaluateEnvironment,
   evaluatePlatform,
   PLATFORM_PROBE,
-  type MachinePlatform,
 } from './machine/platform';
 
 export interface ManagerNode extends NodeReport {
@@ -51,14 +50,14 @@ export type DeployNode = (
 /** Minimal read-only POSIX inspection requires no workspace, Node, Bun or Git. */
 export async function inspectBootstrap(
   node: FleetNode,
-  run: Runner,
-  os: MachinePlatform = 'linux'
+  run: Runner
 ): Promise<Check[]> {
   const result = await run([...sshArgs(node), PLATFORM_PROBE], {
     timeoutMs: 20_000,
   });
   if (!result.ok) return [sshFailure(result)];
-  const baseline = evaluatePlatform(os, result.stdout);
+  const baseline = evaluatePlatform(result.stdout);
+  const environment = evaluateEnvironment(result.stdout);
   return [
     {
       id: 'ssh:fresh-session',
@@ -75,6 +74,15 @@ export async function inspectBootstrap(
           'Review the release/architecture migration in source. No operating-system upgrade or downgrade is performed.',
       },
     },
+    {
+      id: environment.id,
+      status: environment.supported ? 'pass' : 'fail',
+      summary: environment.summary,
+      remedy: {
+        action:
+          'Run the worker on a physical or virtual machine of its own; docs/support-matrix.md lists what is supported.',
+      },
+    },
   ];
 }
 
@@ -124,7 +132,7 @@ export async function synchronizeManager(
   // worker is then verified against.
   if (managerRun) await managerRun;
   const workers = await Promise.all(
-    input.definition.workers.filter(convergeable).map((machine) => {
+    input.definition.workers.map((machine) => {
       input.progress?.(
         machine.id,
         'Inspecting enrolled identity and fresh SSH access'
@@ -329,7 +337,7 @@ async function inspectManagerNode(
       },
     });
   else {
-    checks.push(...(await inspectBootstrap(node, run, machine.os)));
+    checks.push(...(await inspectBootstrap(node, run)));
     checks.push(...identityChecks(node, peer));
     if (peer) checks.push(keyExpiryCheck(peer));
   }

package/src/network-definition.ts

@@ -8,7 +8,7 @@ export interface NetworkHost {
   sshPort: number;
   user: string;
   identityFile: string;
-  os: 'linux' | 'macOS' | 'windows';
+  os: 'linux';
   t3Port: number;
 }
 export function networkProjection(

package/src/node-converge-linux.ts

@@ -66,7 +66,7 @@ export async function convergeLinux(
   checks.push(...(await t3AfterBaseline(root, { node, baseline, run })));
   checks.push(
     ...(await attempt('workstation:configuration', () =>
-      configureWorkstation(root, run)
+      configureWorkstation(root, run, node)
     ))
   );
   checks.push(
@@ -169,7 +169,7 @@ async function applyBaseline(
     },
     {
       name: 'ubuntu-baseline',
-      sources: [ubuntu],
+      sources: [ubuntu, resolve(root, 'ansible/github')],
       force,
       verify: () => baselineServicesActive(run),
     }
@@ -207,6 +207,7 @@ async function baselineServicesActive(run: Runner): Promise<boolean> {
     'is-active',
     '--quiet',
     'personal-worker-auth.timer',
+    'personal-worker-github.timer',
   ]);
   return user.ok;
 }

package/src/node-converge-shared.ts

@@ -1,6 +1,7 @@
 import { fingerprint, writeReceipt } from './fingerprint';
 import { configureWorkspace } from './configure';
 import { stableWorkspace } from './platform/t3-policy';
+import { convergeGithub } from './github/converge';
 import type { Check, Runner } from './types';
 
 /** Phase wrapper: one failure code per phase, durations measured, no exception text. */
@@ -30,11 +31,13 @@ export async function attempt(
 }
 
 /** The `devfleet` launcher (linked to the applied revision, never copied) and
- * this worker's own credential refresh. Identical on Linux and macOS.
+ * this worker's own credential refresh: its Vault session and, apart from it,
+ * its GitHub sign-in. Identical on Linux and macOS.
  */
 export async function configureWorkstation(
   root: string,
-  run: Runner
+  run: Runner,
+  node?: string
 ): Promise<Check[]> {
   const installed = await run(
     // The stable path of the applied revision: it survives pruning.
@@ -62,6 +65,7 @@ export async function configureWorkstation(
       summary:
         'The devfleet launcher is linked to the applied revision; authentication remains a separate gate.',
     },
+    await convergeGithub(root, run, node),
   ];
 }
 

package/src/node-converge.ts

@@ -23,7 +23,7 @@ async function main(): Promise<Check[]> {
       summary: 'PLATFORM_UNSUPPORTED',
       remedy: {
         action:
-          'Workers are Ubuntu 26.04. The macOS manager converges itself locally in fleet-sync.',
+          'Workers run an Ubuntu release docs/support-matrix.md lists. The macOS manager converges itself locally in fleet-sync.',
       },
     },
   ];

package/src/platform/debian-version.ts

@@ -0,0 +1,62 @@
+/** Debian version ordering, as `dpkg --compare-versions` applies it:
+ * epoch, then upstream version, then revision. Negative when `a` sorts
+ * before `b`, zero when they are the same version, positive after. */
+export function compareDebianVersions(a: string, b: string): number {
+  const [epochA, upstreamA, revisionA] = split(a);
+  const [epochB, upstreamB, revisionB] = split(b);
+  return (
+    epochA - epochB ||
+    comparePart(upstreamA, upstreamB) ||
+    comparePart(revisionA, revisionB)
+  );
+}
+
+function split(version: string): [number, string, string] {
+  const colon = version.indexOf(':');
+  const epoch = colon > 0 ? Number(version.slice(0, colon)) || 0 : 0;
+  const rest = colon > 0 ? version.slice(colon + 1) : version;
+  const dash = rest.lastIndexOf('-');
+  return dash > 0
+    ? [epoch, rest.slice(0, dash), rest.slice(dash + 1)]
+    : [epoch, rest, '0'];
+}
+
+/** `~` sorts before everything, even the end of the string; letters sort
+ * before every other character. */
+function order(char: string | undefined): number {
+  if (char === undefined) return 0;
+  if (char === '~') return -1;
+  if (/[A-Za-z]/.test(char)) return char.charCodeAt(0);
+  return char.charCodeAt(0) + 256;
+}
+
+/** Alternating runs: text, then digits, then text again, starting with text. */
+function runs(part: string): string[] {
+  return part
+    .match(/\D*\d*/g)!
+    .filter(Boolean)
+    .flatMap((run) => {
+      const digits = /\d*$/.exec(run)![0];
+      return [run.slice(0, run.length - digits.length), digits];
+    });
+}
+
+function compareText(a: string, b: string): number {
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    const difference = order(a[i]) - order(b[i]);
+    if (difference) return difference;
+  }
+  return 0;
+}
+
+function comparePart(a: string, b: string): number {
+  const left = runs(a);
+  const right = runs(b);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 2) {
+    const difference =
+      compareText(left[i] ?? '', right[i] ?? '') ||
+      Number(left[i + 1] || 0) - Number(right[i + 1] || 0);
+    if (difference) return difference;
+  }
+  return 0;
+}

package/src/platform/ubuntu-audit.ts

@@ -1,5 +1,5 @@
-import policy from '../../ansible/ubuntu/policy.json';
 import type { Runner } from '../types';
+import { packagePins, UBUNTU_RELEASES, ubuntuRelease } from './ubuntu-release';
 
 export interface UbuntuAudit {
   supported: boolean;
@@ -11,7 +11,13 @@ export interface UbuntuAudit {
   passwordlessSudo: boolean;
   rebootPending: boolean;
 }
-const PACKAGES = [...Object.keys(policy.packages), 'tailscale'];
+// Every package any accepted release pins, so one audit serves them all.
+const PACKAGES = [
+  ...new Set([
+    ...UBUNTU_RELEASES.flatMap((release) => Object.keys(packagePins(release))),
+    'tailscale',
+  ]),
+];
 
 /** Read-only audit: never emit package sources, environment, accounts or raw errors. */
 export async function auditUbuntu(run: Runner): Promise<UbuntuAudit> {
@@ -32,14 +38,15 @@ export async function auditUbuntu(run: Runner): Promise<UbuntuAudit> {
   const version =
     /^VERSION_ID="?([0-9]+\.[0-9]+)"?$/m.exec(release.stdout)?.[1] ?? null;
   const reported = arch.stdout.trim();
-  const architecture = policy.architectures.includes(reported)
+  const accepted = ubuntuRelease(version);
+  const architecture = accepted?.architectures.includes(reported)
     ? reported
     : null;
   return {
     supported:
       release.ok &&
       /^ID=ubuntu$/m.test(release.stdout) &&
-      version === policy.release &&
+      accepted !== undefined &&
       architecture !== null,
     release: version,
     architecture,

package/src/platform/ubuntu-release.ts

@@ -0,0 +1,41 @@
+import policy from '../../ansible/ubuntu/policy.json';
+
+/** One Ubuntu release workers may run. The accepted releases are named once,
+ * in ansible/ubuntu/policy.json; nothing else spells a release or codename. */
+export interface UbuntuRelease {
+  release: string;
+  codename: string;
+  /** Debian architecture names, as `dpkg --print-architecture` reports them. */
+  architectures: string[];
+  /** Pins of this release that differ from the policy's `packages`. */
+  packages?: Record<string, string>;
+}
+
+export const UBUNTU_RELEASES: readonly UbuntuRelease[] = policy.releases;
+
+/** The package pins of one release: the policy's, with the release's own
+ * pins over them (as tasks/release.yml combines them for Ansible). */
+export function packagePins(
+  release: UbuntuRelease | undefined
+): Record<string, string> {
+  return { ...policy.packages, ...release?.packages };
+}
+
+/** `uname -m` for each Debian architecture name. */
+const KERNEL_ARCHITECTURES: Record<string, string> = {
+  amd64: 'x86_64',
+  arm64: 'aarch64',
+};
+
+export function ubuntuRelease(
+  version: string | null | undefined
+): UbuntuRelease | undefined {
+  return UBUNTU_RELEASES.find((entry) => entry.release === version);
+}
+
+/** The `uname -m` names one release runs on. */
+export function kernelArchitectures(release: UbuntuRelease): string[] {
+  return release.architectures.map(
+    (name) => KERNEL_ARCHITECTURES[name] ?? name
+  );
+}

package/src/remote-bootstrap.ts

@@ -23,6 +23,7 @@ import {
 import { record } from './config';
 import { installedDefinition, type FleetDefinition } from './definition';
 import { cleanCheck, validCheck } from './protocol';
+import { UBUNTU_RELEASES } from './platform/ubuntu-release';
 
 export interface BootstrapPayload {
   revision: string;
@@ -127,6 +128,7 @@ export async function bootstrapRemote(
     payload.digest,
     node.id,
     transfer.mode,
+    UBUNTU_RELEASES.map((entry) => entry.release).join(' '),
   ]
     .map(shellQuote)
     .join(' ');

package/src/repair-catalog.ts

@@ -141,8 +141,8 @@ export const REPAIR_RECIPES: RepairRecipe[] = [
   login(
     'copilot',
     'Sign in to Copilot',
-    [['copilot', 'login']],
-    'Complete native login; provider authorization still needs supported operator diagnostics. No model prompt is used for health checking.'
+    [],
+    'Copilot CLI uses the node’s GitHub sign-in, which fleet-sync brings from the stored credential (github-token). Run fleet-sync; store a fine-grained token with the Copilot Requests permission if auth:copilot says the token kind is refused. No per-node copilot login.'
   ),
   login(
     'gemini',

package/src/secrets.ts

@@ -12,10 +12,13 @@ export const SECRET_NAMES = [
   'monitoring-tunnel-token',
   'proxy-tunnel-token',
 ] as const;
-/** Secrets only a feature the fleet declares needs: a Vault location may
- * leave them out, and they are then unavailable.
+/** Secrets a fleet may leave undeclared. A Vault fleet that names no location
+ * for the GitHub token keeps it where dev-fleet always read it (see
+ * `vaultLocation`); the others are needed only by a feature the fleet
+ * declares, and are otherwise unavailable.
  */
 export const OPTIONAL_SECRET_NAMES = [
+  'github-token',
   // The off-machine storage of the monitoring hub's backups
   // (services.monitoring.backups).
   'monitoring-backup-access-key',
@@ -52,16 +55,53 @@ export type SecretCommand = (
 ) => Promise<string | null>;
 
 /** One read of one secret for this node. Null when it is not available; the
- * value is never logged, printed or placed in argv.
+ * value is never logged, printed or placed in argv. `node` names a node's own
+ * copy of a secret that is kept once per node (`secretVariant`).
  */
-export type SecretsProvider = (name: SecretName) => Promise<string | null>;
+export type SecretsProvider = (
+  name: SecretName,
+  node?: string
+) => Promise<string | null>;
 
 const present = (value: string | null | undefined): string | null =>
   value?.trim() ? value.trim() : null;
 
 /** `proxy-client-key` is read from `DEVFLEET_SECRET_PROXY_CLIENT_KEY`. */
-export const envName = (name: SecretName): string =>
-  `DEVFLEET_SECRET_${name.toUpperCase().replaceAll('-', '_')}`;
+export const envName = (name: SecretName, node?: string): string =>
+  `DEVFLEET_SECRET_${secretVariant(name, node).toUpperCase().replaceAll('-', '_')}`;
+
+/** The name of a node's own copy of a secret: `github-token` of `worker-one`
+ * is `github-token-worker-one` (`DEVFLEET_SECRET_GITHUB_TOKEN_WORKER_ONE`, the
+ * file or sops key `github-token-worker-one`, the Vault field `FIELD_WORKER_ONE`).
+ */
+export const secretVariant = (name: SecretName, node?: string): string =>
+  node ? `${name}-${node}` : name;
+
+/** Where a Vault fleet keeps a secret. The GitHub token was always read from
+ * the field `GITHUB_TOKEN` beside the proxy client key; a fleet that names no
+ * location of its own keeps it there.
+ */
+export function vaultLocation(
+  config: Extract<SecretsConfig, { provider: 'vault' }>,
+  name: SecretName,
+  node?: string
+): VaultLocation | null {
+  const location =
+    config.locations[name as keyof typeof config.locations] ??
+    (name === 'github-token'
+      ? {
+          path: config.locations['proxy-client-key'].path,
+          field: 'GITHUB_TOKEN',
+        }
+      : null);
+  if (!location) return null;
+  return node
+    ? {
+        path: location.path,
+        field: `${location.field}_${node.toUpperCase().replaceAll('-', '_')}`,
+      }
+    : location;
+}
 
 export function secretsProvider(
   config: SecretsConfig,
@@ -74,29 +114,34 @@ export function secretsProvider(
   const env = options.env ?? process.env;
   const run = options.run ?? execute;
   if (config.provider === 'env')
-    return async (name) => present(env[envName(name)]);
+    return async (name, node) => present(env[envName(name, node)]);
   if (config.provider === 'file') {
     // One private file per secret, named after it.
     const directory =
       config.directory ??
       join(options.home ?? homedir(), '.config/dev-fleet/secrets');
-    return async (name) =>
-      present(await readFile(join(directory, name), 'utf8').catch(() => null));
+    return async (name, node) =>
+      present(
+        await readFile(
+          join(directory, secretVariant(name, node)),
+          'utf8'
+        ).catch(() => null)
+      );
   }
   if (config.provider === 'sops')
     // An age- (or KMS-) encrypted document with one top-level key per secret.
-    return async (name) =>
+    return async (name, node) =>
       present(
         await run([
           'sops',
           '--decrypt',
           '--extract',
-          `["${name}"]`,
+          `["${secretVariant(name, node)}"]`,
           config.file,
         ])
       );
-  return async (name) => {
-    const location = config.locations[name];
+  return async (name, node) => {
+    const location = vaultLocation(config, name, node);
     if (!location) return null;
     return present(
       await run([

package/src/service-auth.ts

@@ -1,4 +1,5 @@
 import { record } from './config';
+import { copilotCheck } from './github/copilot';
 import type { Check, CommandResult, Runner } from './types';
 
 interface Service {
@@ -48,8 +49,6 @@ export async function codingAuth(
 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.',
 };
@@ -101,6 +100,7 @@ export async function serviceAuth(run: Runner): Promise<Check[]> {
   ];
   const checks: Check[] = [];
   for (const service of services) checks.push(await serviceCheck(service, run));
+  checks.push(await copilotCheck(run));
   for (const [id, reason] of Object.entries(PROXY_ROUTED))
     checks.push({
       id: `auth:${id}`,

package/src/worker-access-checks.ts

@@ -4,29 +4,79 @@ import { secretsProvider } from './secrets';
 import { registry } from './agents/registry';
 import { resolveVaultConfig, usesVault } from './vault-config';
 import { record } from './config';
+import { githubCredential } from './github/credential';
+import { hostId } from './topology';
+import { hostname } from 'node:os';
+import { githubSignInState } from './github/sync';
 
 /** Inject every subprocess; never put credentials in argv, reports, or logs. */
-export async function workerAccessChecks(run: Runner): Promise<Check[]> {
-  const policy = fleet.worker!;
-  const github = await run(['gh', 'api', 'user', '--jq', '.login']);
+export async function workerAccessChecks(
+  run: Runner,
+  nodeId?: string
+): Promise<Check[]> {
   return [
-    {
-      id: 'worker:github-principal',
-      status:
-        github.ok && github.stdout.trim() === policy.githubLogin
-          ? 'pass'
-          : 'fail',
-      summary:
-        'Worker GitHub authentication must match the declared common account.',
-      remedy: {
-        action:
-          'Authenticate this worker with the declared GitHub account. Credentials stay on their original machines.',
-      },
-    },
+    await githubSync(run, nodeId),
     await proxyAuthentication(run),
     ...(usesVault() ? [await vaultRenewalCheck(run)] : []),
   ];
 }
+
+const GITHUB_REMEDIES: Record<string, string> = {
+  GITHUB_TOKEN_MISSING:
+    'The secrets provider holds no GitHub token for this worker. Store it under github-token (github-token-<node> with github.credential "per-node"); the next sign-in job or fleet-sync signs the worker in.',
+  GITHUB_TOKEN_REJECTED:
+    'GitHub refuses the stored token: it was revoked or has expired. Store a new one under github-token; nothing about the secret store itself needs fixing.',
+  GITHUB_LOGIN_MISMATCH:
+    'The stored token belongs to another account than worker.githubLogin. Store the fleet login’s token, or correct worker.githubLogin in the fleet configuration.',
+  GITHUB_UNREACHABLE:
+    'GitHub did not answer from this worker. Check its network and DNS; the worker keeps the sign-in it has.',
+  GITHUB_SIGN_IN_FAILED:
+    'The stored token is valid but this worker has not adopted it. Inspect the job with: journalctl --user -u personal-worker-github.service, or run fleet-sync.',
+};
+
+/** GitHub sign-in is measured on its own, so a GitHub fault is never reported
+ * as a fault of the secret store's renewal, and the code names the system to
+ * fix.
+ */
+async function githubSync(run: Runner, nodeId?: string): Promise<Check> {
+  const login = fleet.worker?.githubLogin;
+  if (!login)
+    return {
+      id: 'worker:github-sync',
+      status: 'fail',
+      summary: 'GITHUB_LOGIN_UNDECLARED',
+      remedy: {
+        action: 'Declare the fleet GitHub login as worker.githubLogin.',
+      },
+    };
+  const code = await githubSignInState({
+    run,
+    login,
+    token: githubCredential(fleet, nodeId ?? hostId(hostname()), secrets(run)),
+  });
+  return code === 'GITHUB_OK'
+    ? {
+        id: 'worker:github-sync',
+        status: 'pass',
+        summary:
+          'Worker GitHub authentication matches the declared common account.',
+      }
+    : {
+        id: 'worker:github-sync',
+        status: 'fail',
+        summary: code,
+        remedy: { action: GITHUB_REMEDIES[code]! },
+      };
+}
+
+const secrets = (run: Runner) =>
+  secretsProvider(fleet.secrets, {
+    run: async (argv) => {
+      const result = await run(argv, { timeoutMs: 20_000 });
+      return result.ok ? result.stdout : null;
+    },
+  });
+
 /** Vault refuses a read the token's policy does not allow with a 403. */
 const PERMISSION_DENIED = /permission denied|Code: 403/i;