@crvouga/dev-fleet 0.1.0 → 0.2.0

package/package.json

@@ -1,16 +1,21 @@
 {
   "name": "@crvouga/dev-fleet",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Keeps a set of development machines in sync: one manager and many workers",
   "license": "MIT",
   "repository": "github:crvouga/dev-fleet",
   "homepage": "https://github.com/crvouga/dev-fleet#readme",
+  "bugs": {
+    "url": "https://github.com/crvouga/dev-fleet/issues"
+  },
   "type": "module",
   "bin": {
     "devfleet": "./bin/devfleet.mjs"
   },
   "files": [
     "bin",
+    "llms.txt",
+    "docs",
     "src",
     "agents",
     "ansible",
@@ -52,6 +57,9 @@
     "yaml": "^2.8.0"
   },
   "devDependencies": {
+    "@cucumber/cucumber-expressions": "20.1.0",
+    "@cucumber/gherkin": "42.0.1",
+    "@cucumber/messages": "34.2.1",
     "@eslint/js": "^9.25.0",
     "@types/bun": "^1.3.9",
     "@types/node": "^22.15.29",
@@ -63,5 +71,6 @@
   "packageManager": "bun@1.4.4",
   "engines": {
     "node": ">=22"
-  }
+  },
+  "gitHead": "6dee8455d48203125eb5c0546c3c4446034fca85"
 }

package/schema/fleet.schema.json

@@ -27,7 +27,8 @@
       "properties": {
         "id": {
           "type": "string",
-          "pattern": "^[a-z][a-z0-9-]{0,62}$"
+          "pattern": "^[a-z][a-z0-9-]{0,62}$",
+          "description": "A short stable id for the manager, used in reports."
         },
         "os": {
           "const": "macOS"
@@ -39,11 +40,13 @@
           "properties": {
             "tailscaleName": {
               "type": "string",
-              "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,252}$"
+              "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,252}$",
+              "description": "The manager's Tailscale MagicDNS name, without the trailing dot (tailscale status --json: .Self.DNSName)."
             },
             "user": {
               "type": "string",
-              "pattern": "^[a-z_][a-z0-9_.-]{0,31}$"
+              "pattern": "^[a-z_][a-z0-9_.-]{0,31}$",
+              "description": "The manager's login name (id -un)."
             }
           }
         },
@@ -64,11 +67,13 @@
         "properties": {
           "id": {
             "type": "string",
-            "pattern": "^[a-z][a-z0-9-]{0,62}$"
+            "pattern": "^[a-z][a-z0-9-]{0,62}$",
+            "description": "A short stable id for the worker. The first worker listed is the canary: a revision new to the fleet must pass there before the others receive it."
           },
           "ssh": {
             "type": "string",
-            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,252}$"
+            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,252}$",
+            "description": "The worker's Host alias in the manager's ~/.ssh/config. It must work with BatchMode=yes and a host key already in known_hosts."
           },
           "os": {
             "const": "linux",
@@ -81,21 +86,25 @@
             "properties": {
               "tailscaleName": {
                 "type": "string",
-                "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,252}$"
+                "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,252}$",
+                "description": "The worker's Tailscale MagicDNS name, without the trailing dot."
               },
               "user": {
                 "type": "string",
-                "pattern": "^[a-z_][a-z0-9_-]{0,31}$"
+                "pattern": "^[a-z_][a-z0-9_-]{0,31}$",
+                "description": "The non-root worker account that can use sudo."
               },
               "sshPort": {
                 "type": "integer",
                 "minimum": 1,
-                "maximum": 65535
+                "maximum": 65535,
+                "description": "The port sshd listens on, normally 22."
               },
               "t3Port": {
                 "type": "integer",
                 "minimum": 1,
-                "maximum": 65535
+                "maximum": 65535,
+                "description": "The port the worker T3 server listens on, normally 3773."
               }
             }
           }
@@ -163,7 +172,8 @@
         "architectures": {
           "const": ["amd64", "arm64"]
         }
-      }
+      },
+      "description": "The supported worker release and architectures (fixed)."
     },
     "worker": {
       "type": "object",
@@ -191,15 +201,18 @@
               "workstation",
               "worker"
             ]
-          }
+          },
+          "description": "Readiness checks every worker must pass; normally all six."
         },
         "githubLogin": {
           "type": "string",
-          "pattern": "^[a-zA-Z0-9-]{1,39}$"
+          "pattern": "^[a-zA-Z0-9-]{1,39}$",
+          "description": "The GitHub login every worker must be signed in as."
         },
         "vaultUser": {
           "type": "string",
-          "pattern": "^[a-zA-Z0-9_.-]{1,64}$"
+          "pattern": "^[a-zA-Z0-9_.-]{1,64}$",
+          "description": "The Vault user each worker's own token is issued for."
         },
         "toolchain": {
           "const": "mise.lock"
@@ -216,13 +229,14 @@
         "neverSleep": {
           "const": true
         }
-      }
+      },
+      "description": "Policy every worker must meet. All but the two logins and the capabilities are fixed."
     },
     "source": {
       "type": "object",
       "additionalProperties": false,
       "required": ["repository"],
-      "description": "The Git repository that holds this fleet's configuration and pins. Nodes only accept source from it.",
+      "description": "The Git repository machines take dev-fleet's code from: the one the package you run was published from, or your fork. Nodes only accept source from it.",
       "properties": {
         "repository": {
           "type": "string",
@@ -230,6 +244,48 @@
         }
       }
     },
+    "state": {
+      "description": "The bucket that holds the fleet state (the roster, the approved revision and the configuration last applied). Any S3-compatible service, or a directory. Never credentials: a devfleet command reads those from DEVFLEET_BUCKET_ACCESS_KEY_ID and DEVFLEET_BUCKET_SECRET_ACCESS_KEY.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["bucket"],
+          "properties": {
+            "bucket": {
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$"
+            },
+            "endpoint": {
+              "type": "string",
+              "description": "The https origin of the S3 service; omit for AWS S3.",
+              "pattern": "^https://[A-Za-z0-9.-]{1,253}(:[0-9]{1,5})?$"
+            },
+            "region": {
+              "type": "string",
+              "pattern": "^[a-z0-9-]{1,32}$"
+            },
+            "prefix": {
+              "type": "string",
+              "description": "Key prefix, so one bucket can hold several fleets. Default: dev-fleet.",
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._/-]{0,199}$"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["directory"],
+          "properties": {
+            "directory": {
+              "type": "string",
+              "description": "An absolute path on an attached disk or a mounted share.",
+              "pattern": "^/"
+            }
+          }
+        }
+      ]
+    },
     "secrets": {
       "description": "Where this fleet keeps its secrets. env: DEVFLEET_SECRET_<NAME>; file: one file per secret; sops: one encrypted document; vault: a KV v2 location per secret.",
       "oneOf": [

package/src/agents/fleet-verify.ts

@@ -135,6 +135,14 @@ const UPSTREAM: Record<string, string> = {
     'The provider did not answer within the bounded verification deadline. Retry later.',
 };
 
+/** The declared route cannot work as it is: it fails, and stays failed,
+ * until the route is changed. Retrying or signing in again changes nothing.
+ */
+const INCOMPATIBLE: Record<string, string> = {
+  PROVIDER_PROTOCOL_INCOMPATIBLE:
+    'The gateway does not serve the protocol this route uses (no such endpoint, method or media type). Nothing on this machine can fix it: change the route in agents/registry.json to one listed under "Supported alternatives" in agents/setup.md, then run fleet-sync.',
+};
+
 export function inferenceFailure(provider: string, code: string): Check {
   if (QUOTA.has(code))
     return {
@@ -150,6 +158,7 @@ export function inferenceFailure(provider: string, code: string): Check {
     remedy: {
       action:
         upstream ??
+        INCOMPATIBLE[code] ??
         `Verify unattended Vault access and the declared ${provider} model on the singleton gateway. Preserve OAuth state; do not log native auth on proxy clients.`,
     },
   };

package/src/agents/native-verify.ts

@@ -23,6 +23,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 +32,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 +40,7 @@ export const NATIVE_AGENTS = [
     binary: 'grok',
     pin: 'http:grok',
     wrapper: 'grok-proxy.ts',
+    launcher: 'grok-proxy.ts',
     args: ['-p', PROMPT],
   },
   {
@@ -44,6 +48,7 @@ export const NATIVE_AGENTS = [
     binary: 'antigravity',
     pin: 'http:antigravity',
     wrapper: 'antigravity-proxy.ts',
+    launcher: 'antigravity-proxy.ts',
     args: [
       '-p',
       PROMPT,
@@ -58,14 +63,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 +97,15 @@ export async function verifyNativeAgents(
     /** Proxy routes already found out of quota; their sessions are not run. */
     outOfQuota?: Set<string>;
     cache?: VerifyCache;
+    t3Service?: boolean;
   } = {}
 ): 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,21 +113,24 @@ 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))
+                ),
+                () =>
+                  sessionCheck(agent, { node, workspace, cwd, launch }, run),
+                cache
               ),
-              () => sessionCheck(agent, { node, workspace, cwd }, run),
-              cache
-            ),
       ])
     );
-    return results.flat();
+    return [...environment.checks, ...results.flat()];
   } finally {
     await rm(cwd, { recursive: true, force: true });
   }
@@ -168,19 +198,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 +233,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[],