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

package/dist/config.d.ts

@@ -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 {
@@ -137,6 +142,34 @@ export interface RoleConfig {
     worklog?: WorklogPolicyInput;
     auth_proxy?: Partial<AuthProxyConfig>;
 }
+export type AgentSelection<T extends Record<string, unknown> = Record<string, unknown>> = {
+    ref: string;
+} | {
+    inline: T;
+};
+/** Canonical authoring contract shared by configured, spawned, and room agents. */
+export interface AgentDefinition {
+    role: AgentSelection;
+    brain: AgentSelection;
+    permissions?: Partial<CommonPermissions>;
+    identity?: string;
+    cwd?: string;
+    coordinator?: string;
+    env?: Record<string, string>;
+    oversee?: OverseeEntry[];
+    isolation?: IsolationConfig;
+    monitor?: Partial<MonitorConfig>;
+    owner_channel?: OwnerChannelConfigInput;
+    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;
@@ -147,6 +180,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;
@@ -171,6 +205,13 @@ export interface ResolvedRole extends Omit<RoleConfig, 'model' | 'owner_channel'
     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;
@@ -190,12 +231,20 @@ export interface FieldProvenance {
 }
 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;
     }>;
@@ -229,11 +278,27 @@ export declare function resolveRoleModel(model: string | null | undefined, harne
  */
 export declare function isolationContextFor(role: ResolvedRole): WrapContext;
 export declare const ROLE_NAME_RE: RegExp;
+export declare const ROLE_PRESET_KEYS: string[];
+export declare const BRAIN_PRESET_KEYS: string[];
+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. */
 export declare function loadConfig(configPath?: string, options?: {
     yamlMode?: YamlMode;
+    additionalAgent?: {
+        id: string;
+        definition: AgentDefinition;
+    };
+    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,
@@ -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',
 ];
+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) {
     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,6 +186,40 @@ 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];
@@ -228,7 +269,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 +306,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 +375,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,11 +402,73 @@ 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`);
         const role = selection(a.role, 'role', agent.file, roles, ROLE_PRESET_KEYS);
@@ -392,8 +540,16 @@ 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,
+        };
         documents.push({ file: agent.file,
-            doc: { roles: { [id]: { ...brainValue, ...roleValue, ...operational } } }, provenance });
+            doc: { roles: { [id]: { ...brainValue, ...roleValue, ...operational } } }, provenance,
+            agentSelections: structuredClone({ role: canonicalDefinition.role, brain: canonicalDefinition.brain }),
+            agentDefinition: canonicalDefinition,
+            ...(agentTemplate ? { agentTemplate } : {}) });
     }
     return documents;
 }
@@ -411,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)) {
@@ -429,14 +588,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 +609,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 +641,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,6 +699,8 @@ export function loadConfig(configPath, options = {}) {
                 auth_proxy: authProxy,
                 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.
@@ -545,7 +716,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 +734,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 +749,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 +772,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 +781,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 +803,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
@@ -685,8 +892,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 +913,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 +1025,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 +1041,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 +1159,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;
 }