@crvouga/dev-fleet 0.1.0 → 0.3.0

package/src/agents/native-verify.ts

@@ -4,6 +4,13 @@ import { join } from 'node:path';
 import type { Check, Runner } from '../types';
 import { pinnedPath } from './toolchain';
 import { registry } from './registry';
+import type { Account } from './accounts';
+import { accountSlug } from './accounts';
+import {
+  accountSessionChecks,
+  sessionResult,
+  type Instance,
+} from '../accounts/sessions';
 import {
   cacheKey,
   cachedCheck,
@@ -23,6 +30,8 @@ export const NATIVE_AGENTS = [
     binary: 'claude',
     pin: 'claude',
     wrapper: 'claude-proxy.ts',
+    // T3's binaryPath: the Claude Agent SDK runs a `.ts` path with node.
+    launcher: 'claude-proxy',
     args: ['-p', PROMPT],
   },
   {
@@ -30,6 +39,7 @@ export const NATIVE_AGENTS = [
     binary: 'codex',
     pin: 'codex',
     wrapper: 'codex-proxy.ts',
+    launcher: 'codex-proxy.ts',
     args: ['exec', '--skip-git-repo-check', PROMPT],
   },
   {
@@ -37,6 +47,7 @@ export const NATIVE_AGENTS = [
     binary: 'grok',
     pin: 'http:grok',
     wrapper: 'grok-proxy.ts',
+    launcher: 'grok-proxy.ts',
     args: ['-p', PROMPT],
   },
   {
@@ -44,6 +55,7 @@ export const NATIVE_AGENTS = [
     binary: 'antigravity',
     pin: 'http:antigravity',
     wrapper: 'antigravity-proxy.ts',
+    launcher: 'antigravity-proxy.ts',
     args: [
       '-p',
       PROMPT,
@@ -58,14 +70,31 @@ export const NATIVE_AGENTS = [
     binary: 'opencode',
     pin: 'aqua:anomalyco/opencode',
     wrapper: 'opencode-proxy.ts',
+    launcher: 'opencode-proxy.ts',
     args: ['run', '--model', 'personal_proxy/devin/muse-wonder-1-0', PROMPT],
   },
 ] as const;
 
 type Agent = (typeof NATIVE_AGENTS)[number];
 
+/** The user service T3 runs as on a worker, and so the environment every
+ * agent it starts inherits.
+ */
+export const T3_SERVICE = 't3code-desktop.service';
+
+/** How a session is launched: by the sync, through Bun on the pinned PATH,
+ * or exactly as the T3 service starts it, with that service's environment
+ * and nothing of the sync's.
+ */
+type Launch =
+  | { kind: 'sync' }
+  | { kind: 'service'; env: Record<string, string> }
+  | { kind: 'incomplete' };
+
 /** Same versions everywhere (from the shared mise.lock) and a working signed-in
  * session through each T3 launcher. Agents run concurrently and are bounded.
+ * With `t3Service` (a Linux worker), sessions run in the environment of the
+ * T3 user service, where T3 itself starts them, not in the sync's.
  */
 export async function verifyNativeAgents(
   node: string,
@@ -75,10 +104,20 @@ export async function verifyNativeAgents(
     /** Proxy routes already found out of quota; their sessions are not run. */
     outOfQuota?: Set<string>;
     cache?: VerifyCache;
+    t3Service?: boolean;
+    /** The proxy's accounts and what this node offers. Every cached result
+     * is keyed on the roster version and the client key's version, so any
+     * account change or key rotation re-verifies at once.
+     */
+    accounts?: AccountContext;
   } = {}
 ): Promise<Check[]> {
   const { outOfQuota = new Set<string>(), cache = {} } = options;
   const pins = parsePins(await readFile(join(workspace, 'mise.toml'), 'utf8'));
+  const environment = options.t3Service
+    ? await serviceLaunch(run)
+    : { launch: { kind: 'sync' } as Launch, checks: [] };
+  const { launch } = environment;
   const cwd = await mkdtemp(join(tmpdir(), 'fleet-agents-'));
   try {
     const results = await Promise.all(
@@ -86,26 +125,143 @@ export async function verifyNativeAgents(
         await versionCheck(agent, pins[agent.pin], run),
         outOfQuota.has(agent.name)
           ? quotaPass(agent)
-          : await cachedCheck(
-              `agent-${node}-${agent.name}`,
-              cacheKey(
-                node,
-                agent,
-                pins[agent.pin] ?? '',
-                registry,
-                await sourceKey(launcherSources(workspace, agent))
+          : launch.kind === 'incomplete'
+            ? incompleteSession(agent)
+            : await cachedCheck(
+                `agent-${node}-${agent.name}`,
+                cacheKey(
+                  node,
+                  agent,
+                  pins[agent.pin] ?? '',
+                  registry,
+                  await sourceKey(launcherSources(workspace, agent)),
+                  options.accounts?.rosterVersion ?? '',
+                  options.accounts?.keyVersion ?? ''
+                ),
+                () =>
+                  sessionCheck(agent, { node, workspace, cwd, launch }, run),
+                cache
               ),
-              () => sessionCheck(agent, { node, workspace, cwd }, run),
-              cache
-            ),
       ])
     );
-    return results.flat();
+    const accounts =
+      options.accounts && launch.kind !== 'incomplete'
+        ? await accountSessionChecks(
+            options.accounts.live,
+            options.accounts.exposed,
+            (instance) =>
+              accountSession(instance, options.accounts!, {
+                node,
+                workspace,
+                cwd,
+                launch,
+                cache,
+                run,
+              })
+          )
+        : [];
+    return [...environment.checks, ...results.flat(), ...accounts];
   } finally {
     await rm(cwd, { recursive: true, force: true });
   }
 }
 
+export interface AccountContext {
+  live: Account[];
+  exposed: Instance[];
+  rosterVersion: string;
+  keyVersion: string;
+}
+
+/** How a per-account instance is launched: its tool's launcher, pinned to
+ * the account as T3 pins it.
+ */
+const ACCOUNT_LAUNCH: Record<
+  string,
+  { wrapper: string; launcher: string; args: string[] }
+> = {
+  claude: {
+    wrapper: 'claude-proxy.ts',
+    launcher: 'claude-proxy',
+    args: ['-p', PROMPT],
+  },
+  codex: {
+    wrapper: 'codex-proxy.ts',
+    launcher: 'codex-proxy.ts',
+    args: ['exec', '--skip-git-repo-check', PROMPT],
+  },
+  opencode: {
+    wrapper: 'opencode-proxy.ts',
+    launcher: 'opencode-proxy.ts',
+    args: ['run', PROMPT],
+  },
+};
+
+async function accountSession(
+  instance: Instance,
+  accounts: AccountContext,
+  context: {
+    node: string;
+    workspace: string;
+    cwd: string;
+    launch: Launch;
+    cache: VerifyCache;
+    run: Runner;
+  }
+): Promise<'ok' | 'cooling-down' | 'failed'> {
+  const spec = ACCOUNT_LAUNCH[instance.tool];
+  if (!spec) return 'failed';
+  const check = await cachedCheck(
+    `account-${context.node}-${instance.tool}-${accountSlug(instance.account)}`,
+    cacheKey(
+      context.node,
+      instance,
+      spec,
+      accounts.rosterVersion,
+      accounts.keyVersion
+    ),
+    async () => {
+      const agents = join(context.workspace, 'agents');
+      const service = context.launch.kind === 'service';
+      const result = await context.run(
+        service
+          ? [join(agents, spec.launcher), ...spec.args]
+          : ['bun', join(agents, spec.wrapper), ...spec.args],
+        {
+          cwd: context.cwd,
+          env: {
+            ...(context.launch.kind === 'service'
+              ? context.launch.env
+              : { PATH: pinnedPath() }),
+            WS_AGENT_NODE: context.node,
+            WS_AGENT_ACCOUNT: instance.account,
+          },
+          ...(service ? { isolatedEnv: true } : {}),
+          input: '',
+          timeoutMs: 150_000,
+        }
+      );
+      const outcome = sessionResult(result.ok, result.stdout + result.stderr);
+      return {
+        id: 'account-session',
+        status:
+          outcome === 'ok'
+            ? 'pass'
+            : outcome === 'cooling-down'
+              ? 'warn'
+              : 'fail',
+        summary: outcome,
+      };
+    },
+    context.cache
+  );
+  return check.status === 'pass'
+    ? 'ok'
+    : check.status === 'warn'
+      ? 'cooling-down'
+      : 'failed';
+}
+
 /** Reads `tool = "x"` and `"tool" = { version = "x", ... }` pins. */
 export function parsePins(source: string): Record<string, string> {
   const pins: Record<string, string> = {};
@@ -168,19 +324,26 @@ function quotaPass(agent: Agent): Check {
 
 async function sessionCheck(
   agent: Agent,
-  context: { node: string; workspace: string; cwd: string },
+  context: { node: string; workspace: string; cwd: string; launch: Launch },
   run: Runner
 ): Promise<Check> {
+  const agents = join(context.workspace, 'agents');
+  const command =
+    context.launch.kind === 'service'
+      ? [join(agents, agent.launcher), ...agent.args]
+      : ['bun', join(agents, agent.wrapper), ...agent.args];
+  const env =
+    context.launch.kind === 'service'
+      ? { ...context.launch.env, WS_AGENT_NODE: context.node }
+      : { WS_AGENT_NODE: context.node, PATH: pinnedPath() };
   const launch = () =>
-    run(
-      ['bun', join(context.workspace, 'agents', agent.wrapper), ...agent.args],
-      {
-        cwd: context.cwd,
-        env: { WS_AGENT_NODE: context.node, PATH: pinnedPath() },
-        input: '',
-        timeoutMs: 150_000,
-      }
-    );
+    run(command, {
+      cwd: context.cwd,
+      env,
+      ...(context.launch.kind === 'service' ? { isolatedEnv: true } : {}),
+      input: '',
+      timeoutMs: 150_000,
+    });
   const expected = /\bOK\b/;
   let result = await launch();
   // One retry: a CLI's first launch on a node may still be initializing.
@@ -196,6 +359,114 @@ async function sessionCheck(
   };
 }
 
+/** The environment of the T3 user service: what its user manager holds
+ * (PATH included) and what the unit adds. Every launcher starts with
+ * `#!/usr/bin/env bun` or runs `bun`, so that PATH must find Bun.
+ */
+async function serviceLaunch(
+  run: Runner
+): Promise<{ launch: Launch; checks: Check[] }> {
+  const manager = await run(['systemctl', '--user', 'show-environment'], {
+    timeoutMs: 15_000,
+  });
+  const unit = await run(
+    [
+      'systemctl',
+      '--user',
+      'show',
+      T3_SERVICE,
+      '--property=Environment',
+      '--value',
+    ],
+    { timeoutMs: 15_000 }
+  );
+  if (!manager.ok || !unit.ok)
+    return {
+      launch: { kind: 'sync' },
+      checks: [
+        environmentCheck(
+          'warn',
+          'AGENT_SERVICE_ENVIRONMENT_UNVERIFIED',
+          'The environment of the T3 service could not be read, so sessions were launched from the sync instead. Inspect the user service manager of this worker: systemctl --user show-environment.'
+        ),
+      ],
+    };
+  const env = {
+    ...parseAssignments(manager.stdout.split('\n')),
+    ...parseAssignments(words(unit.stdout)),
+  };
+  const bun = await run(['/bin/sh', '-c', 'command -v bun'], {
+    env,
+    isolatedEnv: true,
+    timeoutMs: 15_000,
+  });
+  if (!bun.ok)
+    return {
+      launch: { kind: 'incomplete' },
+      checks: [
+        environmentCheck(
+          'fail',
+          'AGENT_SERVICE_ENVIRONMENT_INCOMPLETE',
+          INCOMPLETE_REMEDY
+        ),
+      ],
+    };
+  return {
+    launch: { kind: 'service', env },
+    checks: [
+      environmentCheck(
+        'pass',
+        'The T3 service environment finds Bun; every session was launched with it alone.'
+      ),
+    ],
+  };
+}
+
+const INCOMPLETE_REMEDY = `The PATH of ${T3_SERVICE} does not find Bun, so T3 cannot start any agent launcher even though they work from a shell. Put the pinned shims on the PATH of the user service manager through the baseline (never by hand), then run fleet-sync.`;
+
+function environmentCheck(
+  status: Check['status'],
+  summary: string,
+  remedy?: string
+): Check {
+  return {
+    id: 'agent:service-environment',
+    status,
+    summary,
+    ...(remedy ? { remedy: { action: remedy } } : {}),
+  };
+}
+
+function incompleteSession(agent: Agent): Check {
+  return {
+    id: `agent:${agent.name}:session`,
+    status: 'fail',
+    summary: 'AGENT_SERVICE_ENVIRONMENT_INCOMPLETE',
+    remedy: { action: INCOMPLETE_REMEDY },
+  };
+}
+
+/** `KEY=value` lines or words; a value systemd quoted loses its quotes. */
+function parseAssignments(entries: string[]): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const entry of entries) {
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/s.exec(entry.trim());
+    if (match) env[match[1]!] = unquote(match[2]!);
+  }
+  return env;
+}
+
+/** `systemctl show -p Environment` separates assignments with spaces and
+ * double-quotes one that holds a space.
+ */
+function words(line: string): string[] {
+  return line.trim().match(/(?:[^\s"]+|"[^"]*")+/g) ?? [];
+}
+
+function unquote(value: string): string {
+  return value.replace(/"([^"]*)"/g, '$1').replace(/^\$'(.*)'$/s, '$1');
+}
+
 /** A stable code only; raw CLI output is never reported. */
 function sessionFailure(output: string): string {
   if (/missing or out of date/.test(output)) return 'AGENT_PROFILE_STALE';

package/src/agents/provider-errors.ts

@@ -8,9 +8,15 @@ export class ProviderVerificationError extends AgentConfigurationError {
     super(message);
   }
 }
+/** The gateway has no such route, method or media type for this protocol:
+ * the route as declared cannot work, whatever the account.
+ */
+const INCOMPATIBLE = new Set([404, 405, 415, 501]);
+
 export function providerHttpFailure(status: number): ProviderVerificationError {
-  const code =
-    status === 401 || status === 403
+  const code = INCOMPATIBLE.has(status)
+    ? 'PROVIDER_PROTOCOL_INCOMPATIBLE'
+    : status === 401 || status === 403
       ? 'PROVIDER_AUTH_REJECTED'
       : status === 429
         ? 'PROVIDER_RATE_LIMITED'
@@ -27,6 +33,7 @@ const SAFE_CODES = new Set([
   'PROVIDER_RATE_LIMITED',
   'PROVIDER_UPSTREAM_UNAVAILABLE',
   'PROVIDER_PROTOCOL_REJECTED',
+  'PROVIDER_PROTOCOL_INCOMPATIBLE',
   'PROVIDER_MODEL_UNAVAILABLE',
   'PROVIDER_OUTPUT_UNVERIFIED',
   'PROVIDER_TOOL_RESULT_UNVERIFIED',

package/src/agents/registry.ts

@@ -14,7 +14,13 @@ export type Selection = {
 /** The tracked registry plus the proxy endpoint from this fleet's config. */
 export const registry = {
   ...source,
-  proxy: { endpoint: fleet.services.proxy.endpoint, ...source.proxy },
+  proxy: {
+    // Read on use: a command that reaches no proxy needs no configuration.
+    get endpoint(): string {
+      return fleet.services.proxy.endpoint;
+    },
+    ...source.proxy,
+  },
 };
 
 export function select(node: string, tool: string, profile: string): Selection {

package/src/cli/agent-guide.ts

@@ -4,6 +4,7 @@ const SAFETY = [
   'No arguments prints help, including on a TTY. --json returns this document. The menu requires --interactive; --json and --non-interactive never prompt.',
   'Diagnostics, onboarding instructions, schema, catalogs, scripts and repair previews are read-only.',
   'fleet-sync, fleet-node-sync, t3-apply and t3-cleanup apply by invocation; --dry-run previews. t3-apply --import ID explicitly adopts ownership. --json never implies a dry run. fleet-node-add and fleet-repair require --apply --yes.',
+  'fleet-state alone is read-only; --init, --import, --push and --restore each act on invocation. Bucket credentials come from DEVFLEET_BUCKET_ACCESS_KEY_ID and DEVFLEET_BUCKET_SECRET_ACCESS_KEY or a terminal prompt, never from arguments.',
   'Do not copy credentials, forward SSH agents, bypass host keys, provision infrastructure or execute unreviewed remedies.',
   'A healthy manager does not prove another machine can connect to it. Run fleet-status from each intended manager.',
   'fleet-repair executes only allowlisted owner actions, then reruns diagnostics. Native logins, host trust and resource permissions remain explicit operator steps. Pass the reviewed planHash as --plan-hash to reject a changed plan.',
@@ -14,6 +15,7 @@ const SAFETY = [
 const EXAMPLES = [
   'devfleet fleet-node-sync',
   'devfleet fleet-status',
+  'devfleet fleet-state --json',
   'devfleet t3-status',
   'devfleet fleet-status --local --workspace /path/to/personal --json',
   'devfleet fleet-status --json --strict --timeout 120000',
@@ -28,6 +30,23 @@ const EXAMPLES = [
   'devfleet fleet-repair --local --repair workspace --plan-hash <reviewed-sha256> --apply --yes --json',
 ];
 
+/** For an agent working in another project, which is every project that uses
+ * dev-fleet: a change to dev-fleet is asked for, never made in place.
+ */
+function support(release: Release) {
+  return {
+    issues: release.issues ?? null,
+    report:
+      'A defect in dev-fleet, or something it cannot do yet, is raised as an issue in the dev-fleet repository: one issue per bug or feature request, after searching the open ones. From any other project that is the only way to change dev-fleet. Tell the operator what is blocked and link the issue.',
+    never:
+      'Do not edit the installed package, a checkout fleet-sync owns or a file dev-fleet manages on a machine: the next install or fleet-sync replaces each of them. Do not clone dev-fleet to patch it, vendor a modified copy, or hide the defect behind a workaround in the project that holds fleet.json.',
+    include:
+      'devfleet --version, the command and its flags, the error code or the failing check IDs from --json, what happened and what was expected.',
+    withhold:
+      'The issue tracker is public. Leave out credentials, the fleet configuration, hostnames, accounts, domains, tailnet names, paths under a home directory and raw subprocess output.',
+  };
+}
+
 export function agentGuide(release: Release) {
   return {
     version: 1,
@@ -36,21 +55,29 @@ export function agentGuide(release: Release) {
     releasedAt: release.releasedAt,
     invocation: 'devfleet <command> --json --non-interactive',
     discovery: 'devfleet commands --json',
+    setup:
+      'Setting up a fleet from a project: llms.txt and docs/consumer-setup.md in this package (node_modules/@crvouga/dev-fleet/), also at https://github.com/crvouga/dev-fleet/blob/main/docs/consumer-setup.md',
     defaultCommand: 'help',
     help: 'devfleet <command> --help',
     interactive:
       'devfleet --interactive (explicit opt-in; TTY required, disabled in CI)',
     groups: {
       'fleet-*':
-        'Developer computers: fleet-status, fleet-discover, fleet-sync, fleet-node-sync, fleet-repair, fleet-nodes, fleet-node-add',
+        'Developer computers: fleet-status, fleet-discover, fleet-sync, fleet-state, fleet-node-sync, fleet-repair, fleet-nodes, fleet-node-add',
       't3-*': 'Declared T3 provider instances: t3-status, t3-apply, t3-cleanup',
       cliproxy: 'The CLI proxy service on the manager; arguments are forwarded',
     },
     configuration: {
       workspace:
-        '--workspace PATH, PERSONAL_WORKSPACE, closest ancestor mise.toml, then current directory',
+        'The published package itself. Run from a checkout (development): --workspace PATH, PERSONAL_WORKSPACE, then the dev-fleet checkout the command is started in',
       roster:
-        '--config PATH, PERSONAL_FLEET_CONFIG, closest ancestor .fleet.local.json, then ~/.config/personal/fleet.json',
+        '--config PATH, PERSONAL_FLEET_CONFIG, closest ancestor .fleet.local.json, then the roster in the fleet state',
+      definition:
+        'DEVFLEET_CONFIG, then the closest fleet.json in the working directory or above it (the operator’s project), then the configuration fleet-sync last applied from the fleet state (the devfleet CLI on the manager), then the copy fleet-sync installed at ~/.config/dev-fleet/fleet.json',
+      state:
+        'DEVFLEET_STATE or ~/.local/share/dev-fleet/state: a local copy of the roster, the approved revision and the configuration last applied. The bucket named under "state" in the fleet configuration is the source of truth; its credentials are passed in DEVFLEET_BUCKET_ACCESS_KEY_ID and DEVFLEET_BUCKET_SECRET_ACCESS_KEY, or saved by devfleet fleet-state --init in ~/.config/dev-fleet/bucket.json for unattended runs. devfleet fleet-state --json compares the copies',
+      revision:
+        'The commit the published package names (devfleet --version). fleet-sync converges every machine to it; --revision SHA selects another',
     },
     output: {
       stdout:
@@ -70,13 +97,20 @@ export function agentGuide(release: Release) {
         'Default fleet-status tests the manager and all configured nodes. --local tests only this manager; --tailnet and --workers cover Tailscale computers. A missing roster fails explicitly. T3/VS Code end-to-end checks remain manual.',
     },
     safety: SAFETY,
+    support: support(release),
+    toolchain:
+      'On a fleet machine the global mise configuration belongs to dev-fleet: fleet-sync publishes it, and fleet-status fails tool:global-mise-config when anything replaced it. A project pins its own tools in a project mise.toml (mise install --locked in its checkout) and never publishes a global one.',
+    library:
+      'None. The package is the devfleet command: it declares no main or exports, and nothing under src/ is a supported import; any release may change it. Ask for a command in an issue instead.',
     fleetSync: {
       command: 'devfleet fleet-sync',
       preview: 'devfleet fleet-sync --dry-run --json',
-      approval: 'Applies on invocation without a prompt; --dry-run previews',
+      approval:
+        'Applies on invocation without a prompt; --dry-run previews and changes no machine: on the manager it only checks the release out into dev-fleet’s cache and installs the Bun it pins, never the toolchain, the global mise configuration or shell profiles',
       scope:
         'Whole enrolled Ubuntu fleet over verified SSH; --node filters diagnostics/rollout',
-      state: '~/.local/share/personal/fleet/manager/enrollment.json',
+      state:
+        'The approved and applied revision are kept in the fleet state and uploaded to its bucket after every run; the report carries the state:replica check',
       readiness:
         'Full Ubuntu acceptance is incomplete and fails closed; do not override it or claim deployment success.',
     },

package/src/cli/app.ts

@@ -3,13 +3,20 @@ import { resolveSettings, type Settings } from './settings';
 import { COMMANDS } from './registry';
 import { execute } from './program';
 import { parseArgs } from 'node:util';
-import manifest from '../../package.json';
+import { packageInfo } from '../package-info';
 
 /** The manifest carries `0.0.0-development` in the repository; the release
- * workflow stamps the tag's version into the package it publishes.
+ * workflow stamps the tag's version, and the commit, into the package it
+ * publishes.
  */
-export const VERSION = manifest.version;
-const RELEASE = { version: VERSION, releasedAt: null };
+const PACKAGE = packageInfo();
+export const VERSION = PACKAGE.version;
+const RELEASE = {
+  version: VERSION,
+  releasedAt: null,
+  revision: PACKAGE.revision,
+  issues: PACKAGE.issues,
+};
 
 export function wantsInteractive(
   args: string[],

package/src/cli/cli.ts

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
 import { main } from './app';
+import { useProjectConfig } from './project';
+import { actAsOperator } from '../state/operator';
+import { databasePath } from '../state/paths';
+import { readDocument } from '../state/store';
+
+actAsOperator((root) => readDocument(databasePath(root), 'definition'));
+useProjectConfig();
 
 try {
   process.exitCode = await main();

package/src/cli/command-index.ts

@@ -30,6 +30,13 @@ function execution(entry: CommandSpec) {
         'enrolled Ubuntu fleet over verified SSH; manager is not an implicit target',
       note: 'JSON/noninteractive never prompt. Full Ubuntu acceptance is not yet implemented.',
     };
+  if (entry.mutation && entry.id.startsWith('fleet-state '))
+    return {
+      default: 'apply',
+      authorization: 'command-invocation',
+      preview: 'devfleet fleet-state --json',
+      note: 'Each flag is one explicit action on this manager’s fleet state. JSON selects output format; it does not prevent writes.',
+    };
   if (APPLIES.has(entry.id))
     return {
       default: 'apply',