@ours.network/fleet 1.1.0-nightly.10 → 1.1.0-nightly.12

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawn as spawnChild } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync } from 'node:fs';
 import { realpathSync } from 'node:fs';
 import { join as joinPath, resolve as resolvePath } from 'node:path';
 import { createInterface } from 'node:readline';
@@ -9,8 +9,9 @@ import { Command } from 'commander';
 import { VERSION } from './version.js';
 import { INIT_COMPLETION_GUIDANCE } from './init-guidance.js';
 import { bootstrapPresets } from './preset-bootstrap.js';
+import { migrateLegacyStarterPresets } from './preset-migration.js';
 import { analyzeInstalls, buildInfo, buildLabel, discoverInstalls, runningLabel, } from './provenance.js';
-import { agentDir, agentsRoot, tmpRoot, logsRoot, deriveXdgRuntimeDir } from './paths.js';
+import { agentDir, agentsRoot, tmpRoot, logsRoot, deriveXdgRuntimeDir, defaultConfigPath } from './paths.js';
 import { findRole, loadConfig, ROLE_NAME_RE } from './config.js';
 import { formatDuration } from './duration.js';
 import { redactSensitive, resolvedPlan } from './resolved-plan.js';
@@ -394,29 +395,26 @@ cOpt(program.command('force-restart [names...]').description('re-sync + bounce F
         die(e);
     }
 });
-program.command('ls').description('list running fleet sessions')
-    .action(async () => {
+cOpt(program.command('ls').description('list running declared persistent Agent sessions'))
+    .action(async (opts) => {
     const acp = [];
-    for (const root of [agentsRoot(), tmpRoot()]) {
-        if (!existsSync(root))
+    const cfg = loadConfig(opts.configuration);
+    for (const { name } of cfg.roles) {
+        const stateDir = agentDir(name);
+        if (!existsSync(controlSocketPath(stateDir)))
             continue;
-        for (const name of readdirSync(root)) {
-            const stateDir = joinPath(root, name);
-            if (!existsSync(controlSocketPath(stateDir)))
-                continue;
-            try {
-                const response = await controlRequest(stateDir, { command: 'status' }, 2_000);
-                const result = response.result;
-                if (response.ok && result?.alive) {
-                    // Activity, not readiness: an idle-readiness role may be running a
-                    // steered wake turn (FLEET-002), so `ls` reports what was observed.
-                    const observed = classifyActivity(result.activity);
-                    acp.push(`${name}: acp${observed.state === 'active' ? ' (working)'
-                        : observed.state === 'quiet' ? ' (no recent agent activity)' : ''}`);
-                }
+        try {
+            const response = await controlRequest(stateDir, { command: 'status' }, 2_000);
+            const result = response.result;
+            if (response.ok && result?.alive) {
+                // Activity, not readiness: an idle-readiness role may be running a
+                // steered wake turn (FLEET-002), so `ls` reports what was observed.
+                const observed = classifyActivity(result.activity);
+                acp.push(`${name}: acp${observed.state === 'active' ? ' (working)'
+                    : observed.state === 'quiet' ? ' (no recent agent activity)' : ''}`);
             }
-            catch { /* ignore stale sockets */ }
         }
+        catch { /* ignore stale sockets */ }
     }
     console.log(acp.join('\n') || '(none)');
 });
@@ -526,8 +524,9 @@ program.command('logs <name>').description('show the role log').option('-f, --fo
     const { cmd, args } = pickBackend().logsArgs(name, opts.follow === true);
     process.exit(await passthrough(cmd, args));
 });
-program.command('status <name>').description('unit/agent state')
-    .action(async (name) => {
+cOpt(program.command('status <name>').description('declared persistent Agent unit/session state'))
+    .action(async (name, opts) => {
+    findRole(loadConfig(opts.configuration), name);
     console.log(await pickBackend().status(name));
     // A role outlives the artifact that created it. If a different build is
     // reporting now, its settings may resolve differently than at creation.
@@ -1269,6 +1268,26 @@ cOpt(program.command('init').description('idempotent host setup plus missing pac
     console.log(`Created ${seeded.created.length}; preserved ${seeded.preserved.length} existing file(s).`);
     console.log(INIT_COMPLETION_GUIDANCE);
 });
+cOpt(program.command('migrate-agent-templates')
+    .description('dry-run the exact legacy starter split; add --write to apply atomically')
+    .option('--write', 'apply the reviewed migration and retain a private recovery backup'))
+    .action((opts) => {
+    try {
+        const result = migrateLegacyStarterPresets(opts.configuration ?? defaultConfigPath(), { write: opts.write });
+        console.log(result.write ? 'Applied legacy starter migration.' : 'Dry run only; no files were changed.');
+        for (const move of result.moves)
+            console.log(`Move ${move.from} -> ${move.to}`);
+        for (const addition of result.additions)
+            console.log(`Add ${addition}`);
+        console.log(`Staging path: ${result.stagingPath}`);
+        console.log(`Recovery backup: ${result.backupPath}`);
+        if (!result.write)
+            console.log('Re-run with --write to apply this exact migration class.');
+    }
+    catch (error) {
+        die(error);
+    }
+});
 const webCommand = cOpt(program.command('web').description('start or open the secure localhost fleet web console'))
     .enablePositionalOptions()
     .option('--port <port>', 'loopback service port (default: 49271)', value => {

package/dist/config.d.ts

@@ -158,6 +158,13 @@ export interface AgentDefinition {
     worklog?: WorklogPolicyInput;
     auth_proxy?: Partial<AuthProxyConfig>;
 }
+/** Inert, reusable launch definition. It never owns an identity or runtime state. */
+export type AgentTemplateDefinition = Omit<AgentDefinition, 'identity'>;
+/** Explicit persistent instance reusing an inert template. */
+export interface AgentTemplateInstance {
+    template: string;
+    overrides?: Partial<AgentDefinition>;
+}
 /** Internal first-boot payload for a Fleet-provisioned Cowork room member. */
 export interface RoomMemberStartup {
     room_id: string;
@@ -194,6 +201,11 @@ export interface ResolvedRole extends Omit<RoleConfig, 'model' | 'owner_channel'
     roomMemberStartup?: RoomMemberStartup;
     /** Original unresolved selections only; denied operational fields never enter inheritance state. */
     agentSelections?: Pick<AgentDefinition, 'role' | 'brain'>;
+    agentTemplate?: {
+        id: string;
+        sourceFile: string;
+        contentHash: string;
+    };
 }
 export interface FieldProvenance {
     sourceFile: string;
@@ -215,12 +227,18 @@ export interface FleetConfig {
     roles: ResolvedRole[];
     /** Canonical, variable-resolved Agent authoring documents keyed by stable Agent ID. */
     agentDefinitions?: Record<string, AgentDefinition>;
+    /** Canonical inert templates keyed by stable template ID. */
+    agentTemplates?: Record<string, AgentTemplateDefinition>;
+    rolePresets?: Record<string, Record<string, unknown>>;
+    brainPresets?: Record<string, Record<string, unknown>>;
+    /** Required launch-boundary resolver for effective temporary Agent definitions. */
+    resolveAgentDefinition?: (id: string, definition: AgentDefinition) => ResolvedRole;
     vars: Record<string, string>;
     defaults: Record<string, unknown>;
     files: string[];
     configMode?: 'split-v2';
     sourceDocuments?: Array<{
-        kind: 'Manifest' | 'Agent' | 'Role' | 'Brain' | 'RoomTemplate';
+        kind: 'Manifest' | 'Agent' | 'AgentTemplate' | 'Role' | 'Brain' | 'RoomTemplate';
         id?: string;
         path: string;
     }>;
@@ -260,6 +278,8 @@ export declare const AGENT_KEYS: string[];
 type BarePreset = Record<string, unknown>;
 export declare function validateRoleValue(value: BarePreset, file: string, pointer: string): void;
 export declare function validateBrainValue(value: BarePreset, file: string, pointer: string): void;
+/** Pure launch-boundary validation for a fully resolved temporary Agent definition. */
+export declare function validateEffectiveAgentTemplate(definition: AgentTemplateDefinition, id?: string): AgentTemplateDefinition;
 export declare function assertBareKeys(value: unknown, allowed: string[], label: string): BarePreset;
 export declare function splitRootFor(base: string): string;
 /** Load a v2 manifest and bare Agent/Role/Brain documents from its stem directory. */
@@ -271,6 +291,8 @@ export declare function loadConfig(configPath?: string, options?: {
     };
     skipWatchdogs?: boolean;
 }): FleetConfig;
+/** Full read-only Agent resolution used by launch dry-runs and room plan validation. */
+export declare function resolveAgentDefinitionDryRun(configPath: string, id: string, definition: AgentDefinition): ResolvedRole;
 /**
  * Canonical form of a 64-hex container ID for authorization decisions. Hex
  * case is not identity: two casings of one CID are the same peer, so every

package/dist/config.js

@@ -11,6 +11,8 @@ import { validateRoomsConfig, validateTasksConfig, validateRoomTemplatesConfig,
 import { CAPABILITIES, CAP_MONITOR_INTERRUPT_AFTER_TOOL } from './capabilities.js';
 import { runningLabel } from './provenance.js';
 import { parseDuration } from './duration.js';
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.js';
 /** Conservative built-in policy; `worklog: false` is the explicit opt-out. */
 export const DEFAULT_WORKLOG_POLICY = Object.freeze({
     max_kb: 1024,
@@ -142,6 +144,11 @@ export const AGENT_KEYS = [
     'role', 'brain', 'permissions', 'identity', 'cwd', 'coordinator', 'env', 'oversee',
     'isolation', 'monitor', 'owner_channel', 'worklog', 'auth_proxy',
 ];
+const AGENT_INSTANCE_KEYS = ['template', 'overrides'];
+const TEMPLATE_FORBIDDEN_KEYS = ['identity'];
+const MERGED_MAP_FIELDS = new Set([
+    'permissions', 'env', 'isolation', 'monitor', 'owner_channel', 'worklog', 'auth_proxy',
+]);
 const V2_API_VERSION = 'ours.network/fleet/v2';
 const utf8Bytes = (value) => Buffer.byteLength(value, 'utf8');
 function schemaError(file, pointer, summary) {
@@ -179,6 +186,40 @@ export function validateBrainValue(value, file, pointer) {
             schemaError(file, `${pointer}/${key}`, 'must be a mapping');
     }
 }
+/** Pure launch-boundary validation for a fully resolved temporary Agent definition. */
+export function validateEffectiveAgentTemplate(definition, id = 'room-member') {
+    const value = structuredClone(definition);
+    const bad = Object.keys(value).filter(key => !AGENT_KEYS.includes(key));
+    if (bad.length)
+        throw new ConfigError(`member '${id}' has unknown Agent key(s) ${bad.join(', ')}`);
+    if (Object.hasOwn(value, 'identity'))
+        throw new ConfigError(`member '${id}' cannot override identity`);
+    if (!isPlainObject(value.role) || !isPlainObject(value.role.inline)
+        || Object.keys(value.role).some(key => key !== 'inline'))
+        throw new ConfigError(`member '${id}' role must be a resolved inline definition`);
+    if (!isPlainObject(value.brain) || !isPlainObject(value.brain.inline)
+        || Object.keys(value.brain).some(key => key !== 'inline'))
+        throw new ConfigError(`member '${id}' brain must be a resolved inline definition`);
+    const role = value.role.inline;
+    const brain = value.brain.inline;
+    assertBareKeys(role, ROLE_PRESET_KEYS, `member '${id}' Role`);
+    assertBareKeys(brain, BRAIN_PRESET_KEYS, `member '${id}' Brain`);
+    validateRoleValue(role, '(member override)', `/members/${id}/role`);
+    validateBrainValue(brain, '(member override)', `/members/${id}/brain`);
+    validateAgentScalars(Object.fromEntries(Object.entries(value)
+        .filter(([key]) => key !== 'role' && key !== 'brain')), '(member override)', id);
+    resolvePermissions(undefined, value.permissions, '(member override)', id);
+    if (value.isolation !== undefined) {
+        const problems = validateIsolationConfig(value.isolation);
+        if (problems.length)
+            throw new ConfigError(`member '${id}' ${problems.join('; ')}`);
+    }
+    const adapter = getAdapter(brain.harness);
+    adapter.agentSession.resolveBrain({ model: brain.model,
+        effort: brain.effort,
+        harnessOptions: brain.harness_options });
+    return value;
+}
 function validateAgentScalars(value, file, id) {
     for (const key of ['identity', 'cwd']) {
         const current = value[key];
@@ -334,7 +375,23 @@ function deepSubStrict(value, vars, file, pointer) {
         ]));
     return value;
 }
-function composeSplitRoles(base, baseDoc, yamlMode, diagnostics, files, additionalAgent) {
+function mergeTemplateDefinition(template, overrides, file, id) {
+    const merge = (base, overlay, key) => {
+        if (overlay === null && key !== 'model')
+            schemaError(file, `/agents/${id}/overrides/${key}`, 'null deletion is not supported');
+        if (MERGED_MAP_FIELDS.has(key) && isPlainObject(base) && isPlainObject(overlay)) {
+            return Object.fromEntries([...new Set([...Object.keys(base), ...Object.keys(overlay)])]
+                .map(child => [child, Object.hasOwn(overlay, child)
+                    ? merge(base[child], overlay[child], key) : structuredClone(base[child])]));
+        }
+        return structuredClone(overlay);
+    };
+    const result = structuredClone(template);
+    for (const [key, value] of Object.entries(overrides))
+        result[key] = merge(result[key], value, key);
+    return result;
+}
+function composeSplitRoles(base, baseDoc, yamlMode, diagnostics, files, additionalAgent, templateSink = {}, roleSink = {}, brainSink = {}) {
     if (baseDoc.api_version !== V2_API_VERSION)
         throw new ConfigError(`${base}: legacy fleet configuration is unsupported; run 'ours-fleet doctor' and rewrite it as ${V2_API_VERSION}`);
     if ('roles' in baseDoc)
@@ -345,6 +402,7 @@ function composeSplitRoles(base, baseDoc, yamlMode, diagnostics, files, addition
     assertTrustedPath(root, 'directory');
     const brains = readKindDirectory(join(root, 'brains'), 'brain', false, yamlMode, diagnostics, files);
     const roles = readKindDirectory(join(root, 'roles'), 'role', false, yamlMode, diagnostics, files);
+    const agentTemplates = readKindDirectory(join(root, 'agent_templates'), 'agent template', false, yamlMode, diagnostics, files);
     const agents = readKindDirectory(join(root, 'agents'), 'agent', true, yamlMode, diagnostics, files);
     if (additionalAgent) {
         if (agents.has(additionalAgent.id))
@@ -354,9 +412,63 @@ function composeSplitRoles(base, baseDoc, yamlMode, diagnostics, files, addition
         });
     }
     const vars = (baseDoc.vars ?? {});
+    for (const [id, preset] of roles) {
+        const value = assertBareKeys(preset.value, ROLE_PRESET_KEYS, `${preset.file}: Role '${id}'`);
+        validateRoleValue(value, preset.file, `/roles/${id}`);
+        roleSink[id] = deepSubStrict(value, vars, preset.file, `/roles/${id}`);
+    }
+    for (const [id, preset] of brains) {
+        const value = assertBareKeys(preset.value, BRAIN_PRESET_KEYS, `${preset.file}: Brain '${id}'`);
+        validateBrainValue(value, preset.file, `/brains/${id}`);
+        brainSink[id] = deepSubStrict(value, vars, preset.file, `/brains/${id}`);
+    }
+    const canonicalTemplates = new Map();
+    for (const [id, template] of agentTemplates) {
+        const value = assertBareKeys(template.value, AGENT_KEYS, `${template.file}: agent template '${id}'`);
+        if (!('role' in value) || !('brain' in value))
+            throw new ConfigError(`${template.file}: agent template '${id}' requires role and brain`);
+        const forbidden = TEMPLATE_FORBIDDEN_KEYS.filter(key => Object.hasOwn(value, key));
+        if (forbidden.length)
+            schemaError(template.file, `/agent_templates/${id}/${forbidden[0]}`, 'templates cannot own instance identity');
+        const templateRole = selection(value.role, 'role', template.file, roles, ROLE_PRESET_KEYS);
+        const templateBrain = selection(value.brain, 'brain', template.file, brains, BRAIN_PRESET_KEYS);
+        validateRoleValue(templateRole.value, templateRole.file, templateRole.pointer);
+        validateBrainValue(templateBrain.value, templateBrain.file, templateBrain.pointer);
+        validateAgentScalars(Object.fromEntries(Object.entries(value).filter(([key]) => key !== 'role' && key !== 'brain')), template.file, id);
+        canonicalTemplates.set(id, { file: template.file, value });
+        const operational = deepSubStrict(Object.fromEntries(Object.entries(value).filter(([key]) => key !== 'role' && key !== 'brain')), vars, template.file, `/agent_templates/${id}`);
+        templateSink[id] = {
+            role: { inline: deepSubStrict(templateRole.value, vars, templateRole.file, templateRole.pointer) },
+            brain: { inline: deepSubStrict(templateBrain.value, vars, templateBrain.file, templateBrain.pointer) },
+            ...operational,
+        };
+    }
     const documents = [];
     for (const [id, agent] of agents) {
-        const a = assertBareKeys(agent.value, AGENT_KEYS, `${agent.file}: agent '${id}'`);
+        let a;
+        let agentTemplate;
+        const instanceKeys = Object.keys(agent.value);
+        if (instanceKeys.includes('template')) {
+            assertBareKeys(agent.value, AGENT_INSTANCE_KEYS, `${agent.file}: agent '${id}'`);
+            if (typeof agent.value.template !== 'string' || !ROLE_NAME_RE.test(agent.value.template))
+                schemaError(agent.file, `/agents/${id}/template`, 'must be a valid Agent Template ID');
+            const template = canonicalTemplates.get(agent.value.template);
+            if (!template)
+                throw new ConfigError(`${agent.file}: E_REF_MISSING: agent template '${agent.value.template}' not found`);
+            if (agent.value.overrides !== undefined && !isPlainObject(agent.value.overrides))
+                schemaError(agent.file, `/agents/${id}/overrides`, 'must be a mapping');
+            const overrides = assertBareKeys((agent.value.overrides ?? {}), AGENT_KEYS, `${agent.file}: agent '${id}' overrides`);
+            a = mergeTemplateDefinition(template.value, overrides, agent.file, id);
+            const resolvedTemplate = templateSink[agent.value.template];
+            agentTemplate = {
+                id: agent.value.template,
+                sourceFile: template.file,
+                contentHash: createHash('sha256').update(canonicalJson(resolvedTemplate)).digest('hex'),
+            };
+        }
+        else {
+            a = assertBareKeys(agent.value, AGENT_KEYS, `${agent.file}: agent '${id}'`);
+        }
         if (!('role' in a) || !('brain' in a))
             throw new ConfigError(`${agent.file}: agent '${id}' requires role and brain`);
         const role = selection(a.role, 'role', agent.file, roles, ROLE_PRESET_KEYS);
@@ -436,7 +548,8 @@ function composeSplitRoles(base, baseDoc, yamlMode, diagnostics, files, addition
         documents.push({ file: agent.file,
             doc: { roles: { [id]: { ...brainValue, ...roleValue, ...operational } } }, provenance,
             agentSelections: structuredClone({ role: canonicalDefinition.role, brain: canonicalDefinition.brain }),
-            agentDefinition: canonicalDefinition });
+            agentDefinition: canonicalDefinition,
+            ...(agentTemplate ? { agentTemplate } : {}) });
     }
     return documents;
 }
@@ -454,6 +567,9 @@ export function loadConfig(configPath, options = {}) {
     const base = configPath ?? defaultConfigPath();
     const files = [];
     const diagnostics = [];
+    const agentTemplates = {};
+    const rolePresets = {};
+    const brainPresets = {};
     let docs = [];
     let manifestDoc = {};
     if (existsSync(base)) {
@@ -472,7 +588,7 @@ export function loadConfig(configPath, options = {}) {
     const dd = fleetDDir();
     if (existsSync(dd) && readdirSync(dd).some(f => f.endsWith('.yaml') || f.endsWith('.yml')))
         throw new ConfigError(`${dd}: legacy fleet.d configuration is unsupported; run 'ours-fleet doctor' and move agents to ${splitRootFor(base)}/agents/`);
-    docs = [{ file: base, doc: manifestDoc }, ...composeSplitRoles(base, manifestDoc, options.yamlMode ?? 'compat', diagnostics, files, options.additionalAgent)];
+    docs = [{ file: base, doc: manifestDoc }, ...composeSplitRoles(base, manifestDoc, options.yamlMode ?? 'compat', diagnostics, files, options.additionalAgent, agentTemplates, rolePresets, brainPresets)];
     const baseDoc = manifestDoc;
     const vars = (baseDoc.vars ?? {});
     const defaults = (baseDoc.defaults ?? {});
@@ -485,7 +601,7 @@ export function loadConfig(configPath, options = {}) {
     const seen = new Map();
     const roles = [];
     const agentDefinitions = {};
-    for (const { file, doc, provenance, agentSelections, agentDefinition } of docs) {
+    for (const { file, doc, provenance, agentSelections, agentDefinition, agentTemplate } of docs) {
         for (const [name, raw] of Object.entries((doc.roles ?? {}))) {
             if (!ROLE_NAME_RE.test(name))
                 throw new ConfigError(`${file}: invalid role name '${name}' (allowed: [A-Za-z0-9_-])`);
@@ -582,6 +698,7 @@ export function loadConfig(configPath, options = {}) {
                 env: Object.keys(env).length ? env : undefined,
                 loops: [],
                 ...(agentSelections ? { agentSelections } : {}),
+                ...(agentTemplate ? { agentTemplate } : {}),
             });
             // Forbidden-path enforcement: a mount that would breach the policy
             // is a configuration error, caught by `config` rather than at launch.
@@ -653,7 +770,7 @@ export function loadConfig(configPath, options = {}) {
         }
     }
     const result = {
-        roles, agentDefinitions, vars, defaults, files, startStaggerMs, diagnostics, watchdogs,
+        roles, agentDefinitions, agentTemplates, rolePresets, brainPresets, vars, defaults, files, startStaggerMs, diagnostics, watchdogs,
         loops: resolvedLoops.loops,
         rooms, roomTemplates, tasks, ownerInviteFingerprint,
         configMode: 'split-v2',
@@ -662,11 +779,18 @@ export function loadConfig(configPath, options = {}) {
                 return { kind: 'Manifest', path };
             const parent = basename(dirname(path));
             const kind = parent === 'agents' ? 'Agent'
-                : parent === 'roles' ? 'Role'
-                    : parent === 'room_templates' ? 'RoomTemplate' : 'Brain';
+                : parent === 'agent_templates' ? 'AgentTemplate'
+                    : parent === 'roles' ? 'Role'
+                        : parent === 'room_templates' ? 'RoomTemplate' : 'Brain';
             return { kind, id: basename(path, extname(path)), path };
         }),
     };
+    Object.defineProperty(result, 'resolveAgentDefinition', {
+        value: (id, definition) => resolveAgentDefinitionDryRun(base, id, definition),
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
     if (ownerInvite !== undefined) {
         Object.defineProperty(result, 'ownerInvite', {
             value: ownerInvite,
@@ -677,6 +801,12 @@ export function loadConfig(configPath, options = {}) {
     }
     return result;
 }
+/** Full read-only Agent resolution used by launch dry-runs and room plan validation. */
+export function resolveAgentDefinitionDryRun(configPath, id, definition) {
+    return findRole(loadConfig(configPath, {
+        additionalAgent: { id, definition }, skipWatchdogs: true,
+    }), id);
+}
 /**
  * Canonical form of a 64-hex container ID for authorization decisions. Hex
  * case is not identity: two casings of one CID are the same peer, so every
@@ -781,7 +911,13 @@ export function resolveOwnerChannelConfig(defaults, role, session, file = 'confi
     };
 }
 function validateOwnerChannelIdentities(roles) {
-    const roleIdentities = new Map(roles.map(role => [role.identity, role.name]));
+    const roleIdentities = new Map();
+    for (const role of roles) {
+        const prior = roleIdentities.get(role.identity);
+        if (prior)
+            throw new ConfigError(`persistent Agents '${prior}' and '${role.name}' resolve to duplicate identity '${role.identity}'`);
+        roleIdentities.set(role.identity, role.name);
+    }
     const channels = new Map();
     for (const role of roles) {
         const identity = role.owner_channel?.identity;
@@ -1007,7 +1143,10 @@ export function resolveMonitorConfig(defMonitor, roleMonitor, labels = {}) {
 }
 export function findRole(cfg, name) {
     const r = cfg.roles.find(r => r.name === name);
-    if (!r)
+    if (!r) {
+        if (cfg.agentTemplates?.[name])
+            throw new ConfigError(`'${name}' is an inert Agent Template, not a persistent Agent; lifecycle commands target only fleet/agents instances`);
         throw new ConfigError(`no such role '${name}' in ${cfg.files.join(', ') || 'config'}`);
+    }
     return r;
 }