@phnx-labs/agents-cli 1.20.70 → 1.20.72

package/dist/lib/devices/fleet.js

@@ -94,6 +94,39 @@ export function runOnDevice(device, cmd, opts = {}) {
         };
     }
 }
+/**
+ * Run `cmd` on THIS machine directly — no ssh. Used by {@link runFleet} for the
+ * self target: a box frequently can't ssh to itself (no self-authorized key, as
+ * `agents fleet update` hit trying to reach zion from zion) and doesn't need to —
+ * `agents upgrade` etc. runs identically as a local process. Mirrors
+ * {@link runOnDevice}'s return shape and never throws. The argv is space-joined
+ * and evaluated by a shell — matching the POSIX-shell ssh path (so PATH-resolved
+ * `agents`, quoting, and `;`/`&&` behave the same). It does NOT replicate the
+ * powershell-device encoding runOnDevice uses (`connect.ts` base64 path): a
+ * Windows self runs under the default OS shell (cmd.exe), which still resolves
+ * `agents` on PATH for the only self commands that matter (`agents upgrade …`).
+ */
+export function runLocalCommand(cmd, opts = {}) {
+    try {
+        const res = spawnSync(cmd.join(' '), {
+            shell: true,
+            encoding: 'utf-8',
+            timeout: opts.timeoutMs ?? 600_000,
+        });
+        return {
+            code: res.status,
+            stdout: res.stdout?.toString() ?? '',
+            stderr: (res.stderr?.toString() ?? '') + (res.error ? String(res.error.message) : ''),
+        };
+    }
+    catch (err) {
+        return {
+            code: 1,
+            stdout: '',
+            stderr: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 /**
  * Build `agents upgrade --yes` argv, optionally pinned to a version/dist-tag.
  * Rejects anything that is not a plain npm version/tag token so a version pin
@@ -110,10 +143,14 @@ export function upgradeCommand(version) {
 }
 /**
  * Execute a command across planned targets. Pure orchestration over
- * {@link runOnDevice}; testable by injecting `runner`. Per-device throws from
- * the runner are recorded as `failed` so one bad device never aborts the rest.
+ * {@link runOnDevice} / {@link runLocalCommand}; testable by injecting either.
+ * The `self` target runs locally so `agents fleet update` upgrades this machine
+ * too instead of failing to ssh to itself. Per-device throws from a runner are
+ * recorded as `failed` so one bad device never aborts the rest.
  */
-export function runFleet(targets, cmd, runner = runOnDevice) {
+export function runFleet(targets, cmd, opts = {}) {
+    const runner = opts.runner ?? runOnDevice;
+    const localRunner = opts.localRunner ?? runLocalCommand;
     const results = [];
     for (const t of targets) {
         if (t.skip) {
@@ -126,7 +163,8 @@ export function runFleet(targets, cmd, runner = runOnDevice) {
             continue;
         }
         try {
-            const res = runner(t.device, cmd);
+            const isSelf = opts.self !== undefined && t.device.name === opts.self;
+            const res = isSelf ? localRunner(cmd) : runner(t.device, cmd);
             const ok = res.code === 0;
             const detail = (res.stderr || res.stdout).trim().slice(0, 200);
             results.push({

package/dist/lib/devices/sync.d.ts

@@ -69,6 +69,36 @@ export declare function runDeviceSync(opts?: {
     soft?: boolean;
     mode?: DeviceSyncMode;
 }): Promise<DeviceSyncResult>;
+export interface EnsureDevicesResult {
+    /** Names newly resolved from Tailscale and upserted into the registry. */
+    registered: string[];
+    /** Names that could not be resolved (not on the tailnet / tailscale absent). */
+    unresolved: string[];
+}
+/**
+ * Pure decision for `ensureDevicesRegistered`: split the wanted names into those
+ * to resolve+register (missing from the registry, present on the tailnet, not
+ * ignored) vs. unresolved (missing and either off-tailnet or ignored). Already-
+ * registered names need nothing. Pure so the bootstrap's filter matrix is
+ * unit-testable without a tailnet or registry writes.
+ */
+export interface WantedPartition {
+    toRegister: string[];
+    unresolved: string[];
+}
+export declare function partitionWantedDevices(wanted: string[], registered: Set<string>, tailscaleNames: Set<string>, ignored: Set<string>): WantedPartition;
+/**
+ * Fresh-machine bootstrap for `agents apply`: given the device names a `fleet:`
+ * manifest wants, register any that aren't in the local registry by resolving
+ * them LIVE from Tailscale — so a freshly-cloned `agents.yaml` (which carries
+ * names only, never IPs/usernames) reconstructs its roster with zero committed
+ * connection details. Soft by design: a missing tailscale binary or an offline
+ * name yields `unresolved` rather than throwing, so `apply` degrades to "these
+ * devices aren't reachable yet" instead of aborting. Reuses the same
+ * parse→withDefaultUser→upsert path as `runDeviceSync`, so a bootstrapped device
+ * is identical to a synced one.
+ */
+export declare function ensureDevicesRegistered(wantedNames: string[]): Promise<EnsureDevicesResult>;
 /**
  * The register/remove/ignore decision for the interactive curation picker.
  * Pure so the highest-risk reconcile logic is unit-testable without a tailnet

package/dist/lib/devices/sync.js

@@ -125,6 +125,56 @@ export async function runDeviceSync(opts = {}) {
         throw err;
     }
 }
+export function partitionWantedDevices(wanted, registered, tailscaleNames, ignored) {
+    const out = { toRegister: [], unresolved: [] };
+    for (const name of wanted) {
+        if (registered.has(name))
+            continue;
+        if (tailscaleNames.has(name) && !ignored.has(name))
+            out.toRegister.push(name);
+        else
+            out.unresolved.push(name);
+    }
+    return out;
+}
+/**
+ * Fresh-machine bootstrap for `agents apply`: given the device names a `fleet:`
+ * manifest wants, register any that aren't in the local registry by resolving
+ * them LIVE from Tailscale — so a freshly-cloned `agents.yaml` (which carries
+ * names only, never IPs/usernames) reconstructs its roster with zero committed
+ * connection details. Soft by design: a missing tailscale binary or an offline
+ * name yields `unresolved` rather than throwing, so `apply` degrades to "these
+ * devices aren't reachable yet" instead of aborting. Reuses the same
+ * parse→withDefaultUser→upsert path as `runDeviceSync`, so a bootstrapped device
+ * is identical to a synced one.
+ */
+export async function ensureDevicesRegistered(wantedNames) {
+    const registryBefore = await loadDevices();
+    const registered = new Set(Object.keys(registryBefore));
+    const missing = wantedNames.filter((n) => !registered.has(n));
+    if (missing.length === 0)
+        return { registered: [], unresolved: [] };
+    let nodes;
+    try {
+        nodes = parseTailscaleStatus(tailscaleStatusJson());
+    }
+    catch {
+        // Tailscale absent/unreachable — nothing resolvable; report all missing.
+        return { registered: [], unresolved: missing };
+    }
+    const ignored = await loadIgnored();
+    const tailscaleNames = new Set(nodes.map((n) => n.name));
+    const { toRegister, unresolved } = partitionWantedDevices(missing, registered, tailscaleNames, ignored);
+    const byName = new Map(nodes.map((n) => [n.name, n]));
+    const localUser = localLoginUser();
+    const done = [];
+    for (const name of toRegister) {
+        const input = withDefaultUser(nodeToDeviceInput(byName.get(name)), registryBefore[name]?.user, localUser);
+        await upsertDevice(name, input);
+        done.push(name);
+    }
+    return { registered: done, unresolved };
+}
 export function planDeviceReconciliation(allNames, keep, registered, ignored) {
     const keepSet = new Set(keep);
     const regSet = new Set(registered);

package/dist/lib/doctor-diff.js

@@ -22,21 +22,19 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, agentConfigDirName } from './agents.js';
-import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getEffectivePromptcutsPath, } from './state.js';
+import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getEffectivePromptcutsPath, getActiveRulesPreset, } from './state.js';
+import { composeRulesFromState } from './rules/compose.js';
 import { getAvailableResources, getActuallySyncedResources, getVersionHomePath, compareVersions, } from './versions.js';
 import { discoverPlugins, marketplaceSpecForName } from './plugins.js';
 import { pluginInstallDir, repairableManifestFields } from './plugin-marketplace.js';
 import { markdownToToml } from './convert.js';
-import { resolveImports, supportsRulesImports } from './rules/compile.js';
-import { listCommandsInVersionHome, getVersionCommandsDir } from './commands.js';
+import { listCommandsInVersionHome, getVersionCommandsDir, listPluginCommandNames } from './commands.js';
 import { shouldInstallCommandAsSkill, commandSkillMatches, commandSkillName } from './command-skills.js';
 import { gooseCommandMatches, gooseCommandsDir } from './goose-commands.js';
 import { supports } from './capabilities.js';
 import { listSkillsInVersionHome, getVersionSkillsDir } from './skills.js';
 import { listHooksInVersionHome, listHookEntriesFromDir } from './hooks.js';
 const RULES_DOC_FILENAME = 'README.md';
-const COMPILED_HEADER = '<!-- Auto-compiled by agents-cli from ~/.agents/rules/AGENTS.md + imports.\n' +
-    '     Edit the source files under ~/.agents/rules/ — edits to this file will be overwritten on next sync. -->\n\n';
 const ALL_KINDS = [
     'commands',
     'skills',
@@ -173,9 +171,16 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
             homePath,
         });
     }
+    // Plugin-bundled commands (installed as `<plugin>-<cmd>`) are source-managed by
+    // their plugin, tracked under the `plugins` kind — not extras. Without this,
+    // `agents doctor` shows every plugin command (swarm-plan, code-review, …) as an
+    // unmanaged extra, mirroring the orphan false-positive the prune path had.
+    const pluginCommands = listPluginCommandNames();
     for (const name of installed) {
         if (seen.has(name))
             continue;
+        if (pluginCommands.has(name))
+            continue;
         const extraHome = asSkill
             ? path.join(agentDir, 'skills', commandSkillName(name), 'SKILL.md')
             : agent === 'goose'
@@ -236,6 +241,14 @@ function dirsContentMatch(src, dst) {
     return true;
 }
 function diffSkills(agent, version, cwd, excludeProject = false) {
+    // Native ~/.agents/skills consumers (Gemini, …) read central skills directly.
+    // The orchestrator DELETES their version-home skills dir (syncResourcesToVersion)
+    // and registers no skills writer, so there is nothing in the version home to
+    // reconcile. Mirror diffVersionSkills' native gate (skills.ts) — without it
+    // every central skill is false-reported `missing` and held as unreconcilable
+    // forever (drift never clears for these agents).
+    if (AGENTS[agent].nativeAgentsSkillsDir)
+        return [];
     const homeDir = getVersionSkillsDir(agent, version);
     const installed = new Set(listSkillsInVersionHome(agent, version));
     const layerBases = buildLayerBases(cwd, 'skills', { excludeProject });
@@ -380,18 +393,27 @@ function listRulesNames(cwd, excludeProject = false) {
     }
     return out;
 }
-function expectedRuleContent(agent, name, sourcePath) {
-    // AGENTS.md on agents without native @-import support is compiled with imports inlined.
-    if (name === 'AGENTS' && !supportsRulesImports(agent)) {
-        const root = readSafe(sourcePath);
-        if (root == null)
+function expectedRuleContent(agent, name, version, sourcePath) {
+    // The instruction file (AGENTS → the agent's CLAUDE.md/GEMINI.md/AGENTS.md)
+    // is COMPOSED from `subrules/` fragments for the version's active preset —
+    // that is exactly what the rules writer emits (see
+    // staleness/writers/rules.ts → composeRulesFromState). Compare against the
+    // same rendering so a correctly-synced home file reconciles instead of being
+    // held forever against the raw `rules/AGENTS.md` (the whole-repo doc, which a
+    // preset composition deliberately never equals — system subrules don't
+    // auto-append). The `agent` is not part of the rendering (every capable agent
+    // gets identical composed bytes); it is kept for symmetry with the writer's
+    // per-agent dispatch and future per-agent presets.
+    if (name === 'AGENTS') {
+        try {
+            return composeRulesFromState({ preset: getActiveRulesPreset(agent, version) }).content;
+        }
+        catch {
+            // No rules.yaml / unknown preset — the writer skips too; treat as unknown.
             return null;
-        // Compile relative to the source's own dir so project-layer AGENTS.md resolves
-        // its imports relative to the project rules dir, not the user one.
-        const baseDir = path.dirname(sourcePath);
-        const { content } = resolveImports(root, baseDir);
-        return COMPILED_HEADER + content;
+        }
     }
+    // Any sibling top-level rules file syncs as a raw copy.
     return readSafe(sourcePath);
 }
 function diffRules(agent, version, cwd, excludeProject = false) {
@@ -418,7 +440,7 @@ function diffRules(agent, version, cwd, excludeProject = false) {
             rows.push({ kind: 'rules', name, status: 'missing', source: src.layer, sourcePath: src.path });
             continue;
         }
-        const expected = expectedRuleContent(agent, name, src.path);
+        const expected = expectedRuleContent(agent, name, version, src.path);
         const actual = readSafe(homePath);
         if (expected == null || actual == null) {
             rows.push({ kind: 'rules', name, status: 'diff', source: src.layer, sourcePath: src.path, homePath });

package/dist/lib/fleet/apply.d.ts

@@ -30,6 +30,10 @@ export interface DiffContext {
     /** agents-cli version the source is on — the fleet target version. */
     targetCliVersion: string;
     sourceAuth: SourceAuth;
+    /** Secrets-bundle names the profile declares. Values are keychain-local and
+     * can't be pushed, so each reachable device surfaces them as a manual recreate
+     * (`needs-secret`) — informational, never an executed mutation. */
+    secretsBundles?: string[];
 }
 /** Pure: desired vs probed -> per-device diff + flat action list. */
 export declare function diffFleet(desired: DeviceDesired[], probes: Map<string, DeviceProbe>, ctx: DiffContext): FleetPlan;

package/dist/lib/fleet/apply.js

@@ -44,6 +44,7 @@ export function diffFleet(desired, probes, ctx) {
         };
         const rowActions = [];
         const loginBlocked = [];
+        const secretsNeeded = [];
         if (probe.reachable) {
             // agents-cli presence.
             if (!probe.cliVersion) {
@@ -82,8 +83,18 @@ export function diffFleet(desired, probes, ctx) {
                     }
                 }
             }
+            // secrets — surfaced, never pushed (values are keychain-local). Declared
+            // once at the manifest level, so every reachable device gets the same
+            // manual-recreate reminder. Not an executable action (see idempotence
+            // check in commands/apply.ts, which excludes needs-* kinds).
+            if (ctx.secretsBundles && ctx.secretsBundles.length > 0) {
+                for (const bundle of ctx.secretsBundles) {
+                    secretsNeeded.push(bundle);
+                    rowActions.push({ device: d.device, kind: 'needs-secret', detail: `recreate secrets bundle '${bundle}' (\`agents secrets create ${bundle}\`)` });
+                }
+            }
         }
-        devices.push({ device: d.device, desired: d, probe, actions: rowActions, loginBlocked });
+        devices.push({ device: d.device, desired: d, probe, actions: rowActions, loginBlocked, secretsNeeded });
         actions.push(...rowActions);
     }
     return { devices, actions };
@@ -161,11 +172,18 @@ export function reconcileDevice(row, device, ctx) {
         steps.push({ kind: 'add-agent', ok: r.code === 0, detail: a.detail });
         ok = ok && r.code === 0;
     }
-    // 3. config sync.
+    // 3. config sync — one `agents sync <scope>` per declared scope. Each scope is
+    // a positional repo target (system/user/project/alias); a bare `agents sync`
+    // would ignore the profile's declared scopes entirely.
     if (row.actions.some((a) => a.kind === 'sync-config')) {
-        const r = sshAgents(['sync']);
-        steps.push({ kind: 'sync-config', ok: r.code === 0, detail: `sync config` });
-        ok = ok && r.code === 0;
+        const scopes = row.desired.sync.length > 0 ? row.desired.sync : [''];
+        let syncOk = true;
+        for (const scope of scopes) {
+            const r = sshAgents(scope ? ['sync', scope] : ['sync']);
+            syncOk = syncOk && r.code === 0;
+        }
+        steps.push({ kind: 'sync-config', ok: syncOk, detail: `sync config (${row.desired.sync.join(', ') || 'default'})` });
+        ok = ok && syncOk;
     }
     // 4. login propagation — one bundle for all pushable agents on this device.
     const pushAgents = [...new Set(row.actions.filter((a) => a.kind === 'push-login').map((a) => a.agent))];
@@ -182,6 +200,11 @@ export function reconcileDevice(row, device, ctx) {
     for (const blocked of row.loginBlocked) {
         steps.push({ kind: 'needs-login', ok: false, detail: `${blocked} needs a manual login (\`agents ssh ${row.device} -- ${blocked}\`)` });
     }
+    // Surface declared secrets bundles as (non-fatal) manual-recreate reminders —
+    // values are keychain-local, never captured or pushed.
+    for (const bundle of row.secretsNeeded) {
+        steps.push({ kind: 'needs-secret', ok: false, detail: `secrets bundle '${bundle}' must exist on ${row.device} (\`agents ssh ${row.device} -- secrets create ${bundle}\`)` });
+    }
     return { device: row.device, ok, steps };
 }
 /** Run a pool of async tasks with a concurrency cap, preserving input order. */

package/dist/lib/fleet/capture.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Serialize the live environment into a `fleet:` manifest.
+ *
+ * `captureFleet` is PURE — it takes the previous manifest plus already-gathered
+ * inputs (device names, per-device agent specs, browser profiles, secret-bundle
+ * names, routine names) and returns the new manifest. All I/O (registry read,
+ * `agents secrets`/`routines` enumeration, YAML write) happens in the command
+ * (`commands/fleet-capture.ts`); keeping this pure makes the privacy contract —
+ * NAMES ONLY, never IPs/usernames — trivially unit-testable.
+ *
+ * Additive by design: it merges OVER an existing manifest and never clobbers a
+ * hand-authored per-device override (`agents:` you set by hand wins over a
+ * captured one). The captured roster reflects live state, so it becomes the
+ * source of truth for WHICH devices exist.
+ */
+import type { FleetManifest, FleetDefaults } from './types.js';
+export interface CaptureInputs {
+    /** Registered, non-control device names to record (the roster — names only). */
+    devices: string[];
+    /** Optional per-device agent specs (e.g. from `--from-pins`), keyed by name. */
+    agentsByDevice?: Record<string, string[]>;
+    /** Fleet defaults to seed when the manifest has none (source's own agents). */
+    defaults?: FleetDefaults;
+    /** Secrets-bundle NAMES to ensure exist (values stay in the keychain). */
+    secretsBundles?: string[];
+    /** Routine NAMES that should be active on the fleet. */
+    routines?: string[];
+}
+/**
+ * Build the new `fleet:` manifest from the previous one and captured inputs.
+ * Pure — no SSH, no filesystem, no registry. The returned object carries device
+ * names + desired state only; a caller that serializes it to YAML can assert no
+ * address/username ever appears.
+ */
+export declare function captureFleet(prev: FleetManifest | undefined, inputs: CaptureInputs): FleetManifest;

package/dist/lib/fleet/capture.js

@@ -0,0 +1,51 @@
+/**
+ * Serialize the live environment into a `fleet:` manifest.
+ *
+ * `captureFleet` is PURE — it takes the previous manifest plus already-gathered
+ * inputs (device names, per-device agent specs, browser profiles, secret-bundle
+ * names, routine names) and returns the new manifest. All I/O (registry read,
+ * `agents secrets`/`routines` enumeration, YAML write) happens in the command
+ * (`commands/fleet-capture.ts`); keeping this pure makes the privacy contract —
+ * NAMES ONLY, never IPs/usernames — trivially unit-testable.
+ *
+ * Additive by design: it merges OVER an existing manifest and never clobbers a
+ * hand-authored per-device override (`agents:` you set by hand wins over a
+ * captured one). The captured roster reflects live state, so it becomes the
+ * source of truth for WHICH devices exist.
+ */
+/**
+ * Build the new `fleet:` manifest from the previous one and captured inputs.
+ * Pure — no SSH, no filesystem, no registry. The returned object carries device
+ * names + desired state only; a caller that serializes it to YAML can assert no
+ * address/username ever appears.
+ */
+export function captureFleet(prev, inputs) {
+    const prevDevices = prev && prev.devices !== 'all' && typeof prev.devices === 'object'
+        ? prev.devices
+        : {};
+    // Roster: explicit map of the captured names. A hand-authored override for a
+    // device that still exists is preserved; a captured agent list only fills in
+    // when the manifest didn't already pin one for that device.
+    const devices = {};
+    for (const name of inputs.devices) {
+        const prevOverride = prevDevices[name] ?? {};
+        const override = { ...prevOverride };
+        const captured = inputs.agentsByDevice?.[name];
+        if (override.agents === undefined && captured && captured.length > 0) {
+            override.agents = captured;
+        }
+        devices[name] = override;
+    }
+    const manifest = {
+        // Keep hand-authored defaults; otherwise seed from the source snapshot.
+        defaults: prev?.defaults ?? inputs.defaults ?? {},
+        devices,
+    };
+    const bundles = inputs.secretsBundles ?? prev?.secrets?.bundles;
+    if (bundles && bundles.length > 0)
+        manifest.secrets = { bundles: [...bundles].sort() };
+    const routines = inputs.routines ?? prev?.routines;
+    if (routines && routines.length > 0)
+        manifest.routines = [...routines].sort();
+    return manifest;
+}

package/dist/lib/fleet/manifest.d.ts

@@ -19,6 +19,12 @@ export interface ResolveContext {
     registeredDevices: string[];
     /** The source machine, always excluded from the target set. */
     source: string;
+    /** Names the bootstrap could not resolve from Tailscale (off-tailnet, ignored,
+     * or a typo). These are SKIPPED with the caller's warning rather than aborting
+     * the whole reconcile — a manifest naming an asleep laptop must not hard-fail
+     * every other device. Without a bootstrap, this is empty and an unregistered
+     * name still throws (genuine misconfig, caught early). */
+    unresolved?: string[];
 }
 /**
  * Expand a manifest into concrete per-device desired states. `devices: all`

package/dist/lib/fleet/manifest.js

@@ -66,7 +66,25 @@ export function parseFleetManifest(raw) {
     else {
         throw new Error(`fleet: devices must be the string 'all' or a mapping of device -> overrides (got ${JSON.stringify(o.devices)}).`);
     }
-    return { defaults, devices };
+    const manifest = { defaults, devices };
+    // Additive, backward-compatible extras (captured by `agents fleet capture`).
+    if (o.secrets !== undefined) {
+        if (typeof o.secrets !== 'object' || o.secrets === null || Array.isArray(o.secrets)) {
+            throw new Error('fleet: secrets must be a mapping with a `bundles:` list.');
+        }
+        const bundles = o.secrets.bundles;
+        if (bundles !== undefined && !isStringArray(bundles)) {
+            throw new Error('fleet: secrets.bundles must be a list of bundle names (e.g. [attio]).');
+        }
+        manifest.secrets = { bundles: bundles };
+    }
+    if (o.routines !== undefined) {
+        if (!isStringArray(o.routines)) {
+            throw new Error('fleet: routines must be a list of routine names.');
+        }
+        manifest.routines = o.routines;
+    }
+    return manifest;
 }
 /** Read a YAML file and extract + validate its `fleet:` block. */
 export function readFleetFile(filePath) {
@@ -115,9 +133,14 @@ export function resolveDesired(manifest, ctx) {
         }
         return out;
     }
+    const unresolved = new Set(ctx.unresolved ?? []);
     for (const [name, override] of Object.entries(manifest.devices)) {
         if (name === ctx.source)
             continue;
+        // Bootstrap couldn't register this name (off-tailnet / ignored / typo) —
+        // skip it (the caller already surfaced it) instead of aborting the run.
+        if (unresolved.has(name))
+            continue;
         if (!ctx.registeredDevices.includes(name)) {
             throw new Error(`fleet: device '${name}' is not a registered device. Run \`agents devices add ${name}\` or fix the manifest.`);
         }

package/dist/lib/fleet/types.d.ts

@@ -42,6 +42,23 @@ export interface FleetDeviceOverride {
 export interface FleetManifest {
     defaults?: FleetDefaults;
     devices: 'all' | Record<string, FleetDeviceOverride>;
+    /**
+     * Fleet-wide extras captured by `agents fleet capture` so a fresh machine can
+     * reconstruct the whole environment, not just installed agents. All additive,
+     * portable, and LEAK-FREE — names only, never connection details.
+     *
+     * (Browser profiles are deliberately NOT captured here: the central `browser:`
+     * block already syncs verbatim via `agents repo push/pull`, so duplicating it
+     * would be redundant — and its ssh:// endpoints can carry `user@host`, which
+     * must never be copied into a second location.)
+     */
+    /** Secrets-bundle NAMES to ensure exist — values live in the keychain and are
+     * never captured or pushed; `apply` surfaces missing bundles to recreate. */
+    secrets?: {
+        bundles?: string[];
+    };
+    /** Routine NAMES that should be active on the fleet (files sync via the repo). */
+    routines?: string[];
 }
 /**
  * A device's desired state after merging defaults with its override and
@@ -74,7 +91,10 @@ export interface DeviceProbe {
     note?: string;
 }
 /** One planned action against a device, in a single reconcile dimension. */
-export type FleetActionKind = 'install-cli' | 'upgrade-cli' | 'add-agent' | 'sync-config' | 'push-login' | 'needs-login';
+export type FleetActionKind = 'install-cli' | 'upgrade-cli' | 'add-agent' | 'sync-config' | 'push-login' | 'needs-login'
+/** Secrets bundles the profile declares but that can't be pushed (values are
+ * keychain-local) — surfaced as a manual recreate, like `needs-login`. */
+ | 'needs-secret';
 export interface FleetAction {
     device: string;
     kind: FleetActionKind;
@@ -101,6 +121,9 @@ export interface DeviceDiff {
     /** Agents that must be logged in on the device but can't be propagated
      * (source token is device-bound, e.g. macOS keychain). Surfaced, not faked. */
     loginBlocked: string[];
+    /** Secrets-bundle names the profile declares that must be recreated on the
+     * device (values are keychain-local — never captured or pushed). Surfaced. */
+    secretsNeeded: string[];
 }
 /** A portable auth file captured from a source agent home, ready to propagate. */
 export interface AuthFilePayload {

package/dist/lib/git.d.ts

@@ -219,6 +219,20 @@ export declare function displayHomePath(dir: string): string;
  * branch reconciles instead of failing with "Need to specify how to reconcile
  * divergent branches".
  */
+/**
+ * Auto-commit the machine's OWN generated per-device meta file
+ * (`devices/<machineId>/agents.yaml`) if it's the dirty state blocking a pull.
+ *
+ * That file is committed + synced (so every machine can introspect every other
+ * machine's pins), but each box rewrites its own copy whenever a pin changes —
+ * leaving the tree perpetually dirty and wedging `agents repo pull` (which
+ * refuses a dirty tree). This durably commits just that one path (explicit
+ * pathspec) so the pull can proceed; genuine user edits to OTHER files are left
+ * untouched and still (correctly) block the pull. No-op when the meta path isn't
+ * inside `dir` (system/extra repos) or isn't dirty. Returns the committed rel
+ * path, or null. `metaAbs` is injectable for tests; defaults to the live path.
+ */
+export declare function commitOwnDeviceMeta(dir: string, metaAbs?: string): Promise<string | null>;
 export declare function pullRepo(dir: string): Promise<{
     success: boolean;
     commit: string;

package/dist/lib/git.js

@@ -10,7 +10,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { IS_WINDOWS, isWindowsAbsolutePath } from './platform/index.js';
-import { getPackageLocalPath } from './state.js';
+import { getPackageLocalPath, getDeviceMetaPath } from './state.js';
 import { DEFAULT_SYSTEM_REPO, systemRepoSlug } from './types.js';
 /**
  * Validate that a clone/pull source uses a safe git transport before it is
@@ -733,9 +733,47 @@ export function displayHomePath(dir) {
  * branch reconciles instead of failing with "Need to specify how to reconcile
  * divergent branches".
  */
+/**
+ * Auto-commit the machine's OWN generated per-device meta file
+ * (`devices/<machineId>/agents.yaml`) if it's the dirty state blocking a pull.
+ *
+ * That file is committed + synced (so every machine can introspect every other
+ * machine's pins), but each box rewrites its own copy whenever a pin changes —
+ * leaving the tree perpetually dirty and wedging `agents repo pull` (which
+ * refuses a dirty tree). This durably commits just that one path (explicit
+ * pathspec) so the pull can proceed; genuine user edits to OTHER files are left
+ * untouched and still (correctly) block the pull. No-op when the meta path isn't
+ * inside `dir` (system/extra repos) or isn't dirty. Returns the committed rel
+ * path, or null. `metaAbs` is injectable for tests; defaults to the live path.
+ */
+export async function commitOwnDeviceMeta(dir, metaAbs = getDeviceMetaPath()) {
+    const resolvedDir = path.resolve(dir);
+    const resolvedMeta = path.resolve(metaAbs);
+    if (resolvedMeta !== resolvedDir && !resolvedMeta.startsWith(resolvedDir + path.sep)) {
+        return null; // meta lives outside this repo — not ours to commit here
+    }
+    const rel = path.relative(resolvedDir, resolvedMeta).split(path.sep).join('/');
+    try {
+        const git = simpleGit(dir);
+        const status = await git.status();
+        const dirty = status.files.some((f) => f.path === rel);
+        if (!dirty)
+            return null;
+        await git.add([rel]);
+        const machine = path.basename(path.dirname(resolvedMeta));
+        await git.commit(`chore(devices): snapshot ${machine} agent pins`, [rel]);
+        return rel;
+    }
+    catch {
+        return null; // best-effort — never let this block the pull path
+    }
+}
 export async function pullRepo(dir) {
     try {
         const git = simpleGit(dir);
+        // Commit this machine's own device-meta first so a per-machine pin change
+        // never wedges the pull. Genuine edits elsewhere still block below.
+        await commitOwnDeviceMeta(dir);
         const status = await git.status();
         if (!status.isClean()) {
             return {

package/dist/lib/hosts/logs.d.ts

@@ -10,6 +10,7 @@
  * runs to be discoverable there first; until then the bounded tail is the safe
  * concise default.) Kept in one place so the two commands can never drift.
  */
+import { type HostTask } from './tasks.js';
 export interface HostLogResult {
     /** False when no host task with this id exists (caller may fall through to sessions). */
     found: boolean;
@@ -21,5 +22,16 @@ export interface HostLogResult {
  * default; `full` dumps the entire raw combined-stdout log.
  */
 export declare function showHostTaskLog(id: string, follow: boolean, full?: boolean): Promise<HostLogResult>;
+/**
+ * Machine-readable form of a host-dispatch task's log — the task record plus its
+ * combined stdout. Powers `agents logs <id> --json` for the host-task branch.
+ * Reconciles a still-'running' record from the remote `.exit` first, like the
+ * text path does.
+ */
+export declare function hostTaskLogJson(id: string): {
+    found: boolean;
+    task?: HostTask;
+    log?: string | null;
+};
 /** Last `n` lines of `text`, prefixed with an elision note when truncated. */
 export declare function tailLines(text: string, n: number): string;