@ours.network/fleet 1.1.0-nightly.2 → 1.1.0-nightly.21

package/dist/config.js

@@ -6,11 +6,13 @@ import { harnessRuntimeDir, resolveIsolation, validateIsolationConfig, } from '.
 import { getAdapter } from './harness/registry.js';
 import { resolveRoleModelEnv } from './model-env.js';
 import { resolveWatchdogs } from './watchdog/config.js';
-import { resolveLoops } from './loops/config.js';
+import { resolveAgentLoops, resolveLoops } from './loops/config.js';
 import { validateRoomsConfig, validateTasksConfig, validateRoomTemplatesConfig, } from './rooms-tasks/config.js';
 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,
@@ -133,21 +135,26 @@ const ROLE_KEYS = [
     'briefing_file', 'model', 'effort', 'model_chain', 'max_tokens', 'autocompact_pct', 'env', 'oversee', 'harness_options',
     'isolation', 'monitor', 'owner_channel', 'worklog', 'auth_proxy',
 ];
-const ROLE_PRESET_KEYS = ['mission', 'persona', 'bio', 'briefing_file'];
-const BRAIN_PRESET_KEYS = [
+export const ROLE_PRESET_KEYS = ['mission', 'persona', 'bio', 'briefing_file'];
+export const BRAIN_PRESET_KEYS = [
     'harness', 'session', 'session_options', 'model', 'model_chain', 'max_tokens',
     'autocompact_pct', 'harness_options', 'effort',
 ];
-const AGENT_KEYS = [
+export const AGENT_KEYS = [
     'role', 'brain', 'permissions', 'identity', 'cwd', 'coordinator', 'env', 'oversee',
-    'isolation', 'monitor', 'owner_channel', 'worklog', 'auth_proxy',
+    'isolation', 'monitor', 'owner_channel', 'worklog', 'auth_proxy', 'loops',
 ];
+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', 'loops',
+]);
 const V2_API_VERSION = 'ours.network/fleet/v2';
 const utf8Bytes = (value) => Buffer.byteLength(value, 'utf8');
 function schemaError(file, pointer, summary) {
     throw new ConfigError(`${file}: E_SCHEMA ${pointer}: ${summary}`);
 }
-function validateRoleValue(value, file, pointer) {
+export function validateRoleValue(value, file, pointer) {
     const limits = {
         mission: { bytes: 16 * 1024, nonblank: true },
         persona: { bytes: 16 * 1024 },
@@ -168,7 +175,7 @@ function validateRoleValue(value, file, pointer) {
         && (typeof value.briefing_file !== 'string' || !value.briefing_file.trim()))
         schemaError(file, `${pointer}/briefing_file`, 'must be a non-blank relative path');
 }
-function validateBrainValue(value, file, pointer) {
+export function validateBrainValue(value, file, pointer) {
     if (typeof value.harness !== 'string' || !value.harness.trim())
         schemaError(file, `${pointer}/harness`, 'is required and must be a registered non-blank harness ID');
     if (value.model !== undefined && value.model !== null
@@ -179,7 +186,45 @@ 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) {
+    if (value.loops !== undefined)
+        resolveAgentLoops(value.loops, {
+            name: id, harness: 'codex', session: 'acp', permissions: {},
+        }, file);
     for (const key of ['identity', 'cwd']) {
         const current = value[key];
         if (current !== undefined && (typeof current !== 'string' || !current.trim()))
@@ -228,7 +273,7 @@ function assertTrustedPath(path, expected) {
     if ((st.mode & 0o022) !== 0)
         throw new ConfigError(`E_FILE_TRUST: ${path} is group/world writable (mode ${(st.mode & 0o777).toString(8)})`);
 }
-function assertBareKeys(value, allowed, label) {
+export function assertBareKeys(value, allowed, label) {
     if (!isPlainObject(value))
         throw new ConfigError(`${label}: E_SCHEMA: must be a mapping`);
     const bad = Object.keys(value).filter(key => !allowed.includes(key));
@@ -265,6 +310,35 @@ function readKindDirectory(root, kind, required, yamlMode, diagnostics, files) {
     }
     return result;
 }
+function readRoomTemplateDirectory(root, yamlMode, diagnostics, files) {
+    if (!existsSync(root))
+        return {};
+    assertTrustedPath(root, 'directory');
+    const result = {};
+    const sources = new Map();
+    const names = readdirSync(root)
+        .filter(name => ['.yaml', '.yml'].includes(extname(name).toLowerCase())).sort();
+    for (const filename of names) {
+        const file = join(root, filename);
+        assertTrustedPath(file, 'file');
+        const id = basename(filename, extname(filename));
+        const previous = sources.get(id);
+        if (previous)
+            throw new ConfigError(`E_DUPLICATE_ID: room template '${id}' defined by both ${previous} and ${file}`);
+        const parsed = parseFleetDocument(file, readFileSync(file, 'utf8'), yamlMode);
+        diagnostics.push(...parsed.diagnostics);
+        if (parsed.value.override_builtin === true)
+            diagnostics.push({
+                severity: 'warning', kind: 'deprecated-field', file, line: 1, column: 1,
+                message: `${file}: override_builtin is deprecated and ignored for a file-backed Room template`,
+            });
+        files.push(file);
+        const validated = validateRoomTemplatesConfig({ [id]: parsed.value }, file)[id];
+        result[id] = { ...validated, sourceFile: file };
+        sources.set(id, file);
+    }
+    return result;
+}
 function selection(raw, kind, agentFile, presets, allowed) {
     if (!isPlainObject(raw))
         schemaError(agentFile, `/${kind}`, 'must be { ref } or { inline }');
@@ -305,7 +379,23 @@ function deepSubStrict(value, vars, file, pointer) {
         ]));
     return value;
 }
-function composeSplitRoles(base, baseDoc, yamlMode, diagnostics, files) {
+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)
@@ -316,13 +406,77 @@ function composeSplitRoles(base, baseDoc, yamlMode, diagnostics, files) {
     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))
+            throw new ConfigError(`agent '${additionalAgent.id}' already exists`);
+        agents.set(additionalAgent.id, {
+            file: '(spawn request)', value: structuredClone(additionalAgent.definition),
+        });
+    }
     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`);
+        if (Object.hasOwn(a, 'loops') && !(additionalAgent?.temporary && additionalAgent.id === id))
+            schemaError(agent.file, `/agents/${id}/loops`, 'is supported only for temporary Agent launches and inert Agent Templates');
         const role = selection(a.role, 'role', agent.file, roles, ROLE_PRESET_KEYS);
         const brain = selection(a.brain, 'brain', agent.file, brains, BRAIN_PRESET_KEYS);
         const operational = deepSubStrict(Object.fromEntries(Object.entries(a).filter(([key]) => key !== 'role' && key !== 'brain')), vars, agent.file, `/agents/${id}`);
@@ -392,8 +546,17 @@ function composeSplitRoles(base, baseDoc, yamlMode, diagnostics, files) {
             : undefined);
         delete provenance.role;
         delete provenance.brain;
+        const canonicalDefinition = {
+            role: deepSubStrict(a.role, vars, agent.file, `/agents/${id}/role`),
+            brain: deepSubStrict(a.brain, vars, agent.file, `/agents/${id}/brain`),
+            ...operational,
+        };
+        const { loops: _temporaryLoops, ...runtimeOperational } = operational;
         documents.push({ file: agent.file,
-            doc: { roles: { [id]: { ...brainValue, ...roleValue, ...operational } } }, provenance });
+            doc: { roles: { [id]: { ...brainValue, ...roleValue, ...runtimeOperational } } }, provenance,
+            agentSelections: structuredClone({ role: canonicalDefinition.role, brain: canonicalDefinition.brain }),
+            agentDefinition: canonicalDefinition,
+            ...(agentTemplate ? { agentTemplate } : {}) });
     }
     return documents;
 }
@@ -411,6 +574,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)) {
@@ -429,14 +595,20 @@ 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)];
+    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 ?? {});
+    const legacyRuntimeDefaults = ['harness', 'model', 'model_chain', 'effort', 'harness_options',
+        'session', 'session_options', 'max_tokens', 'autocompact_pct']
+        .filter(key => Object.hasOwn(defaults, key));
+    if (legacyRuntimeDefaults.length)
+        throw new ConfigError(`${base}: E_LEGACY /defaults: Brain-owned field(s) ${legacyRuntimeDefaults.join(', ')} are unsupported; move them to a Brain definition`);
     const startStaggerMs = resolveStartStaggerMs(baseDoc.start_stagger_ms, base);
     const seen = new Map();
     const roles = [];
-    for (const { file, doc, provenance } of docs) {
+    const agentDefinitions = {};
+    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_-])`);
@@ -444,6 +616,8 @@ export function loadConfig(configPath, options = {}) {
             if (prev)
                 throw new ConfigError(`role '${name}' defined in both ${prev} and ${file}`);
             seen.set(name, file);
+            if (agentDefinition)
+                agentDefinitions[name] = structuredClone(agentDefinition);
             const r = deepSub(raw ?? {}, vars);
             const bad = Object.keys(r).filter(k => !ROLE_KEYS.includes(k));
             if (bad.length)
@@ -474,6 +648,8 @@ export function loadConfig(configPath, options = {}) {
             const worklog = resolveWorklogPolicy(defaults.worklog, r.worklog, file, name);
             const authProxy = resolveAuthProxy(defaults.auth_proxy, r.auth_proxy, file, name);
             const harness = r.harness ?? defaults.harness ?? 'claude-code';
+            if (session === 'codex-app-server' && harness !== 'codex')
+                throw new ConfigError(`${file}: role '${name}' session: codex-app-server requires harness: codex`);
             const defaultHarness = defaults.harness ?? 'claude-code';
             const inheritsModelDefaults = harness === defaultHarness && r.model !== null;
             if (authProxy && harness !== 'claude-code')
@@ -508,7 +684,7 @@ export function loadConfig(configPath, options = {}) {
             defaulted('identity', r.identity !== undefined, r.identity === undefined);
             defaulted('permissions', defaults.permissions !== undefined, defaults.permissions === undefined);
             defaulted('monitor', defaults.monitor !== undefined, defaults.monitor === undefined);
-            roles.push({
+            const resolvedRole = {
                 ...r,
                 name,
                 sourceFile: file,
@@ -530,7 +706,12 @@ export function loadConfig(configPath, options = {}) {
                 auth_proxy: authProxy,
                 env: Object.keys(env).length ? env : undefined,
                 loops: [],
-            });
+                ...(agentSelections ? { agentSelections } : {}),
+                ...(agentTemplate ? { agentTemplate } : {}),
+            };
+            if (agentDefinition?.loops !== undefined)
+                resolvedRole.temporaryLoops = resolveAgentLoops(agentDefinition.loops, resolvedRole, file);
+            roles.push(resolvedRole);
             // Forbidden-path enforcement: a mount that would breach the policy
             // is a configuration error, caught by `config` rather than at launch.
             if (isolation !== undefined) {
@@ -545,7 +726,12 @@ export function loadConfig(configPath, options = {}) {
         }
     }
     validateOwnerChannelIdentities(roles);
-    const watchdogs = resolveWatchdogs(baseDoc, base, roles, vars, defaults);
+    const watchdogs = options.skipWatchdogs ? [] : resolveWatchdogs(baseDoc, base, roles, vars, agentDefinitions, (name, definition) => {
+        const id = `WatchdogAgent${name}`.slice(0, 64);
+        return findRole(loadConfig(base, {
+            yamlMode: options.yamlMode, additionalAgent: { id, definition }, skipWatchdogs: true,
+        }), id);
+    });
     const resolvedLoops = resolveLoops(baseDoc.loops, base, roles, vars);
     for (const role of roles)
         role.loops = resolvedLoops.byRole.get(role.name) ?? [];
@@ -558,6 +744,9 @@ export function loadConfig(configPath, options = {}) {
     let ownerInvite;
     let roomTemplates;
     let tasks;
+    const fileTemplates = readRoomTemplateDirectory(join(splitRootFor(base), 'room_templates'), options.yamlMode ?? 'compat', diagnostics, files);
+    if (Object.keys(fileTemplates).length)
+        roomTemplates = fileTemplates;
     for (const { file, doc } of docs) {
         if (doc.rooms !== undefined) {
             if (rooms)
@@ -570,7 +759,21 @@ export function loadConfig(configPath, options = {}) {
         }
         if (doc.room_templates !== undefined) {
             const validated = validateRoomTemplatesConfig(deepSub(doc.room_templates, vars), file);
-            roomTemplates = { ...(roomTemplates ?? {}), ...validated };
+            const raw = doc.room_templates;
+            for (const [name, template] of Object.entries(validated)) {
+                const shadowed = roomTemplates?.[name];
+                const marker = raw[name]?.override_builtin;
+                if (shadowed && (marker !== true || template.version <= shadowed.version))
+                    throw new ConfigError(`${file}: room_templates.${name} shadows file preset ${shadowed.sourceFile}; `
+                        + 'set override_builtin: true and use a higher version');
+                if (marker === true)
+                    diagnostics.push({
+                        severity: 'warning', kind: 'deprecated-field', file, line: 1, column: 1,
+                        message: `${file}: room_templates.${name}.override_builtin is deprecated; `
+                            + 'it is retained only as an explicit manifest-over-file migration marker',
+                    });
+                roomTemplates = { ...(roomTemplates ?? {}), [name]: { ...template, sourceFile: file } };
+            }
         }
         if (doc.tasks !== undefined) {
             if (tasks)
@@ -579,7 +782,7 @@ export function loadConfig(configPath, options = {}) {
         }
     }
     const result = {
-        roles, 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',
@@ -588,10 +791,18 @@ export function loadConfig(configPath, options = {}) {
                 return { kind: 'Manifest', path };
             const parent = basename(dirname(path));
             const kind = parent === 'agents' ? 'Agent'
-                : parent === 'roles' ? 'Role' : '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,
@@ -602,6 +813,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, temporary: true }, 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
@@ -685,8 +902,8 @@ export function resolveOwnerChannelConfig(defaults, role, session, file = 'confi
     const maxRequestBytes = attachments.max_request_bytes ?? 20 * 1024 * 1024;
     if (maxRequestBytes < maxFileBytes)
         throw new ConfigError(`${file}: role '${name}' owner_channel.attachments.max_request_bytes must be at least max_file_bytes`);
-    if (session !== 'acp')
-        throw new ConfigError(`${file}: role '${name}' owner_channel requires session: acp for correlated final replies`);
+    if (session !== 'acp' && session !== 'codex-app-server')
+        throw new ConfigError(`${file}: role '${name}' owner_channel requires a managed session with correlated final replies`);
     return {
         identity: merged.identity.trim(),
         owners,
@@ -706,7 +923,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;
@@ -812,8 +1035,8 @@ function resolveSession(raw, file, name) {
     if (value === 'tmux')
         throw new ConfigError(`${file}: role '${name}' session: tmux is no longer supported; use session: acp `
             + 'with the Codex or Claude Code adapter');
-    if (value !== 'acp')
-        throw new ConfigError(`${file}: role '${name}' session: must be: acp`);
+    if (value !== 'acp' && value !== 'codex-app-server')
+        throw new ConfigError(`${file}: role '${name}' session: must be: acp, codex-app-server`);
     return value;
 }
 function resolveSessionOptions(defaults, role, session, file, name) {
@@ -828,26 +1051,40 @@ function resolveSessionOptions(defaults, role, session, file, name) {
             ...((defaults?.acp) ?? {}),
             ...(role?.acp ?? {}),
         },
+        codex_app_server: {
+            ...((defaults?.codex_app_server) ?? {}),
+            ...(role?.codex_app_server ?? {}),
+        },
     };
     if (defaults?.tmux !== undefined
         || role?.tmux !== undefined)
         throw new ConfigError(`${file}: role '${name}' session_options.tmux is no longer supported; `
             + 'use session: acp with session_options.acp');
-    const bad = Object.keys(merged).filter(k => k !== 'acp');
+    const bad = Object.keys(merged).filter(k => k !== 'acp' && k !== 'codex_app_server');
     if (bad.length)
         throw new ConfigError(`${file}: role '${name}' session_options: unknown key(s) ${bad.join(', ')}`);
     if (!isPlainObject(merged.acp))
-        throw new ConfigError(`${file}: role '${name}' session_options.${session} must be a map`);
+        throw new ConfigError(`${file}: role '${name}' session_options.acp must be a map`);
+    if (!isPlainObject(merged.codex_app_server))
+        throw new ConfigError(`${file}: role '${name}' session_options.codex_app_server must be a map`);
     const acpBad = Object.keys(merged.acp).filter(k => k !== 'command');
     if (acpBad.length)
         throw new ConfigError(`${file}: role '${name}' session_options.acp: unknown key(s) ${acpBad.join(', ')}`);
-    const command = merged.acp.command;
-    if (command !== undefined
-        && !(typeof command === 'string' && command.trim())
-        && !(Array.isArray(command) && command.length > 0
-            && command.every(v => typeof v === 'string' && v.length > 0)))
-        throw new ConfigError(`${file}: role '${name}' session_options.acp.command must be a non-empty string or string list`);
-    return Object.keys(merged.acp).length ? merged : undefined;
+    const nativeBad = Object.keys(merged.codex_app_server).filter(k => k !== 'command');
+    if (nativeBad.length)
+        throw new ConfigError(`${file}: role '${name}' session_options.codex_app_server: unknown key(s) ${nativeBad.join(', ')}`);
+    for (const [key, command] of [
+        ['acp', merged.acp.command],
+        ['codex_app_server', merged.codex_app_server.command],
+    ]) {
+        if (command !== undefined
+            && !(typeof command === 'string' && command.trim())
+            && !(Array.isArray(command) && command.length > 0
+                && command.every(v => typeof v === 'string' && v.length > 0)))
+            throw new ConfigError(`${file}: role '${name}' session_options.${key}.command must be a non-empty string or string list`);
+    }
+    return Object.keys(merged.acp).length || Object.keys(merged.codex_app_server).length
+        ? merged : undefined;
 }
 export function resolvePermissions(defaults, role, file = 'config', name = 'role') {
     if (defaults !== undefined && !isPlainObject(defaults))
@@ -932,7 +1169,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;
 }

package/dist/creation.d.ts

@@ -156,7 +156,7 @@ export declare function daemonIdentityInventoryProvisioner(env?: NodeJS.ProcessE
 /** Atomically write a bare Agent file, journalling it for rollback. */
 export declare function writeRoleFile(tx: CreationTransaction, file: string, contents: string): void;
 /** Where a setting's effective value came from. */
-export type ProvenanceSource = 'cli' | 'fleet-default' | 'caller-role' | 'built-in';
+export type ProvenanceSource = 'cli' | 'agent-template' | 'fleet-default' | 'caller-role' | 'built-in';
 export interface ProvenanceEntry {
     value: unknown;
     source: ProvenanceSource;

package/dist/creation.js

@@ -374,11 +374,12 @@ export function creationBuildNote(p) {
 export function formatProvenance(p) {
     const mark = {
         cli: 'explicit', 'fleet-default': 'fleet default', 'caller-role': 'caller role',
-        'built-in': 'built-in',
+        'agent-template': 'Agent Template', 'built-in': 'built-in',
     };
     return Object.entries(p.settings)
         .filter(([, e]) => e.value !== undefined)
-        .map(([k, e]) => `    ${k.padEnd(12)} ${String(e.value)}  (${mark[e.source]})`);
+        .map(([k, e]) => `    ${k.padEnd(12)} ${e.value && typeof e.value === 'object'
+        ? JSON.stringify(e.value) : String(e.value)}  (${mark[e.source]})`);
 }
 /** Classify one setting: an explicit CLI value, a fleet default, or built-in. */
 export function provenanceOf(cliValue, fleetDefault, builtIn) {

package/dist/daemon-recovery.d.ts

@@ -0,0 +1,93 @@
+import { type FetchLike } from './monitor.js';
+export declare const DAEMON_RECOVERY_MAX_ATTEMPTS = 6;
+export declare const DAEMON_RECOVERY_INITIAL_BACKOFF_MS = 1000;
+export declare const DAEMON_RECOVERY_MAX_BACKOFF_MS = 5000;
+export declare const DAEMON_RECOVERY_DEADLINE_MS = 60000;
+export interface DaemonGeneration {
+    bootId: string;
+    pid: number;
+    startedAt: number;
+    stateDir: string;
+}
+export type DaemonGenerationProbe = {
+    state: 'ready';
+    generation: DaemonGeneration;
+} | {
+    state: 'unavailable';
+    reason: string;
+};
+export type DaemonGenerationObservation = {
+    kind: 'baseline' | 'stable' | 'available';
+    generation: DaemonGeneration;
+} | {
+    kind: 'changed';
+    previous: DaemonGeneration;
+    generation: DaemonGeneration;
+} | {
+    kind: 'lost' | 'unavailable';
+    previous?: DaemonGeneration;
+    reason: string;
+};
+interface GenerationProbeDeps {
+    readText?(path: string): string;
+    canonicalize?(path: string): string;
+}
+/**
+ * Corroborate the loopback daemon's unauthenticated `/info`, its credentialed
+ * identity-index readiness route, and its local boot-generation record. The
+ * index enforces auth when the daemon visibility requires it; open visibility
+ * deliberately does not. No source is sufficient
+ * alone: `/info` has no boot id, the identity index has no generation, and a
+ * stale `ready` file can outlive the process that wrote it.
+ */
+export declare function probeDaemonGeneration(fetch: FetchLike, env: NodeJS.ProcessEnv, deps?: GenerationProbeDeps): Promise<DaemonGenerationProbe>;
+export declare class DaemonGenerationObserver {
+    private current?;
+    private unavailable;
+    observe(probe: DaemonGenerationProbe): DaemonGenerationObservation;
+}
+export declare function daemonRecoveryBackoff(attempt: number): number;
+export type RecoveryPath = 'agent' | 'owner';
+export type RecoveryPathResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface RoleRecoveryControllerOptions {
+    role: string;
+    identity: string;
+    stateDir: string;
+    now(): number;
+    sleep(ms: number): Promise<void>;
+    recoverAgent(epoch: string): Promise<RecoveryPathResult>;
+    recoverOwner(epoch: string): Promise<RecoveryPathResult>;
+    log(line: string): void;
+}
+export interface RecoveryStatus {
+    version: 1;
+    identity: string;
+    epoch: string;
+    state: 'recovering' | 'recovered' | 'degraded' | 'cancelled';
+    paths: Record<RecoveryPath, {
+        state: 'pending' | 'recovered' | 'degraded';
+        attempts: number;
+        reason?: string;
+    }>;
+    updatedAt: string;
+}
+export declare function readDaemonRecoveryStatus(dir: string): RecoveryStatus | undefined;
+/** Per-role, per-generation bounded recovery with path-level fault isolation. */
+export declare class RoleRecoveryController {
+    private readonly options;
+    private token;
+    private activeEpoch?;
+    private active?;
+    private status?;
+    constructor(options: RoleRecoveryControllerOptions);
+    recover(generation: DaemonGeneration): Promise<RecoveryStatus>;
+    cancel(): void;
+    noteLoss(reason: string): void;
+    private write;
+}
+export {};