@ours.network/fleet 1.1.0-nightly.3 → 1.1.0-nightly.30

package/dist/config.d.ts

@@ -1,7 +1,7 @@
 import { type ConfigDiagnostic, type YamlMode } from './config-yaml.js';
 import type { IsolationConfig, WrapContext } from './isolation/types.js';
 import type { ResolvedWatchdog } from './watchdog/config.js';
-import type { ResolvedLoop, ResolvedRoleLoop } from './loops/config.js';
+import type { AgentLoopsConfig, ResolvedLoop, ResolvedRoleLoop } from './loops/config.js';
 export interface OverseeEntry {
     agent: string;
     interval: string;
@@ -25,7 +25,8 @@ export declare const NOTIFY_EVENT_TYPES: readonly ["message_received", "file_rec
 export type NotifyEventType = (typeof NOTIFY_EVENT_TYPES)[number];
 export type InjectMode = 'notification' | 'full';
 export type MonitorMode = 'fleet' | 'native';
-export type SessionBackendId = 'acp';
+/** Concrete transport selected for a role. Keep provider-native transports explicit. */
+export type SessionBackendId = 'acp' | 'codex-app-server';
 /** Public, harness-neutral permission policy. */
 export type FleetPermissionMode = 'ask' | 'auto' | 'allow';
 /** `deny` is a deprecated, fail-closed compatibility alias retained for old fleet files. */
@@ -44,6 +45,10 @@ export interface SessionOptions {
         /** ACP agent command and arguments. Defaults are supplied by the harness adapter. */
         command?: string | string[];
     };
+    codex_app_server?: {
+        /** App-server command and arguments. Defaults to `codex app-server`. */
+        command?: string | string[];
+    };
 }
 /** Resolved per-role supervisor-monitor config. */
 export interface MonitorConfig {
@@ -157,6 +162,15 @@ export interface AgentDefinition {
     owner_channel?: OwnerChannelConfigInput;
     worklog?: WorklogPolicyInput;
     auth_proxy?: Partial<AuthProxyConfig>;
+    /** Scheduled turns scoped only to temporary launches; persistent Agents reject this field. */
+    loops?: AgentLoopsConfig;
+}
+/** 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 {
@@ -168,6 +182,7 @@ export interface RoomMemberStartup {
     role: string;
     task: string;
     owner_seat_cid: string | null;
+    anonymous?: boolean;
 }
 export interface ResolvedRole extends Omit<RoleConfig, 'model' | 'owner_channel' | 'worklog'> {
     name: string;
@@ -189,11 +204,20 @@ export interface ResolvedRole extends Omit<RoleConfig, 'model' | 'owner_channel'
     worklog?: WorklogPolicy;
     auth_proxy?: AuthProxyConfig;
     loops?: ResolvedRoleLoop[];
+    /** Agent Template-local loops, kept separate from manifest loops until a temp launch. */
+    temporaryLoops?: ResolvedRoleLoop[];
+    /** Durable source of the temporary loop policy; internal and never user-authored. */
+    temporaryLoopSource?: 'agent-template' | 'cli' | 'omitted';
     provenance?: Record<string, FieldProvenance>;
     /** Internal/transient: never accepted as a user-authored RoleConfig key. */
     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 +239,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';
+        kind: 'Manifest' | 'Agent' | 'AgentTemplate' | 'Role' | 'Brain' | 'RoomTemplate';
         id?: string;
         path: string;
     }>;
@@ -260,6 +290,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. */
@@ -268,9 +300,12 @@ export declare function loadConfig(configPath?: string, options?: {
     additionalAgent?: {
         id: string;
         definition: AgentDefinition;
+        temporary?: boolean;
     };
     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

@@ -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,
@@ -140,8 +142,13 @@ export const BRAIN_PRESET_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) {
@@ -179,7 +186,45 @@ 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) {
+    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()))
@@ -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, 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)
@@ -316,6 +406,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))
@@ -325,11 +416,67 @@ 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`);
+        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}`);
@@ -404,10 +551,12 @@ function composeSplitRoles(base, baseDoc, yamlMode, diagnostics, files, addition
             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 });
+            agentDefinition: canonicalDefinition,
+            ...(agentTemplate ? { agentTemplate } : {}) });
     }
     return documents;
 }
@@ -425,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)) {
@@ -443,7 +595,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 ?? {});
@@ -456,7 +608,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_-])`);
@@ -496,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')
@@ -530,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,
@@ -553,7 +707,11 @@ export function loadConfig(configPath, options = {}) {
                 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) {
@@ -586,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)
@@ -598,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)
@@ -607,7 +782,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',
@@ -616,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,
@@ -630,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
@@ -713,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,
@@ -734,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;
@@ -840,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) {
@@ -856,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))
@@ -960,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

@@ -258,11 +258,13 @@ export function daemonIdentityProvisioner(env = process.env, attachClient = atta
             const before = await client.listIdentities();
             const existing = before.find(identity => identity.name === name);
             if (existing) {
+                if (!('kind' in existing))
+                    throw new Error(`identity '${name}' is quarantined; refusing to replace it`);
                 if (existing.temp)
                     throw new Error(`identity '${name}' exists but is temporary; refusing to convert or adopt it`);
                 return; // another reconciler won the create race
             }
-            if (!before.some(identity => identity.kind === 'root'))
+            if (!before.some(identity => 'kind' in identity && identity.kind === 'root'))
                 throw new Error(`cannot create role identity '${name}': this host has no Human identity; run ours onboarding first`);
             let createdHere = false;
             try {
@@ -279,7 +281,7 @@ export function daemonIdentityProvisioner(env = process.env, attachClient = atta
                 // accept only the compatible permanent identity now visible.
                 const after = await client.listIdentities();
                 const raced = after.find(identity => identity.name === name);
-                if (!raced || raced.temp)
+                if (!raced || !('kind' in raced) || raced.temp)
                     throw error;
             }
             if (createdHere && profile.persona && client.setPersona)
@@ -374,11 +376,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) {