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

package/dist/session/control.d.ts

@@ -1,14 +1,15 @@
 import { type Socket } from 'node:net';
-import type { ControlFailureKind, SessionEvent, SessionHandle, SessionSnapshot } from './types.js';
+import type { AgentSession, ControlFailureKind, SessionEvent, SessionSnapshot } from './types.js';
 import type { OwnerChannelHandle, OwnerChannelManagementRequest } from '../owner-channel/channel.js';
 import type { ScheduledLoopManagerHandle } from '../loops/manager.js';
 import type { SpawnOpts } from '../spawn.js';
 import type { ManagedFleetSpawnResult } from '../fleet-proxy.js';
+import { type FleetAuditPresentation, type FleetCommandOutcomeClass } from '../fleet-command-audit.js';
 export interface ControlRequest {
     version: 1 | 2 | 3;
     id: string;
     token: string;
-    command: 'status' | 'snapshot' | 'submit_prompt' | 'respond_permission' | 'interrupt' | 'follow' | 'events_since' | 'owner_channel_manage' | 'loop_status' | 'loop_run_now' | 'loop_disable' | 'loop_enable' | 'reload_config' | 'conversation_page' | 'conversation_follow' | 'submit_prompt_v2' | 'interrupt_v2' | 'respond_permission_v2' | 'fleet_spawn';
+    command: 'status' | 'snapshot' | 'submit_prompt' | 'respond_permission' | 'interrupt' | 'follow' | 'events_since' | 'owner_channel_manage' | 'loop_status' | 'loop_run_now' | 'loop_disable' | 'loop_enable' | 'reload_config' | 'conversation_page' | 'conversation_follow' | 'submit_prompt_v2' | 'interrupt_v2' | 'respond_permission_v2' | 'fleet_spawn' | 'fleet_audit_begin' | 'fleet_audit_finish';
     text?: string;
     permissionId?: string;
     optionId?: string;
@@ -30,6 +31,16 @@ export interface ControlRequest {
     sessionGeneration?: string;
     /** Typed managed-spawn request accepted only over the authenticated role control plane. */
     spawn?: SpawnOpts;
+    audit?: {
+        requestId?: string;
+        argv?: string[];
+        correlationId?: string;
+        class?: FleetCommandOutcomeClass;
+        exitCode?: number;
+        effect?: 'not_started' | 'completed' | 'unknown';
+        resourceIds?: Record<string, string>;
+        presentations?: FleetAuditPresentation[];
+    };
 }
 export interface ControlResponse {
     version: 1;
@@ -48,7 +59,7 @@ export interface RetainedEventPage {
     truncated: boolean;
 }
 /** The one retained-range projection shared by polling and live-follow admission. */
-export declare function retainedEventPage(session: SessionHandle, since: number): RetainedEventPage;
+export declare function retainedEventPage(session: AgentSession, since: number): RetainedEventPage;
 /**
  * One line saying what a control failure does — and does not — prove about the
  * agent. Only `offline` is evidence that it is gone; every other kind used to
@@ -105,7 +116,8 @@ export declare class RoleControlServer {
     private loopManager?;
     private reloadConfig?;
     private fleetSpawner?;
-    constructor(stateDir: string, session: SessionHandle, log: (line: string) => void);
+    private fleetAuditor?;
+    constructor(stateDir: string, session: AgentSession, log: (line: string) => void);
     start(): Promise<void>;
     close(): Promise<void>;
     /** Attach only the already-started supervisor-owned channel client. */
@@ -113,6 +125,7 @@ export declare class RoleControlServer {
     setLoopManager(loopManager: ScheduledLoopManagerHandle | undefined): void;
     setConfigReloader(reloadConfig: (() => Promise<unknown>) | undefined): void;
     setFleetSpawner(fleetSpawner: ((options: SpawnOpts) => Promise<ManagedFleetSpawnResult>) | undefined): void;
+    setFleetAuditor(auditor: RoleControlServer['fleetAuditor']): void;
     private accept;
     private handle;
     /** Version and capability gate shared by every conversation v3 command. */

package/dist/session/control.js

@@ -3,6 +3,7 @@ import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node
 import { createConnection, createServer } from 'node:net';
 import { join } from 'node:path';
 import { SessionControlError } from './types.js';
+import { validateFleetAuditBegin, validateFleetAuditFinish, } from '../fleet-command-audit.js';
 import { interruptSession, queueSessionPrompt, respondSessionPermission, respondSessionPermissionV2, } from '../application/session-mutations.js';
 const MAX_LINE_BYTES = 64 * 1024;
 /** Commands that require protocol version 3. */
@@ -119,6 +120,7 @@ export class RoleControlServer {
     loopManager;
     reloadConfig;
     fleetSpawner;
+    fleetAuditor;
     constructor(stateDir, session, log) {
         this.session = session;
         this.log = log;
@@ -164,6 +166,7 @@ export class RoleControlServer {
     setFleetSpawner(fleetSpawner) {
         this.fleetSpawner = fleetSpawner;
     }
+    setFleetAuditor(auditor) { this.fleetAuditor = auditor; }
     accept(socket) {
         this.sockets.add(socket);
         socket.setEncoding('utf8');
@@ -311,6 +314,38 @@ export class RoleControlServer {
                     this.write(socket, { version: 1, id: request.id, ok: true, result });
                     return;
                 }
+                case 'fleet_audit_begin': {
+                    if (!this.fleetAuditor)
+                        throw new SessionControlError('rejected', 'fleet auditing is unavailable');
+                    try {
+                        validateFleetAuditBegin(request.audit);
+                    }
+                    catch {
+                        throw new SessionControlError('rejected', 'valid fleet audit begin fields are required');
+                    }
+                    const result = await this.fleetAuditor.begin(request.audit.requestId, request.audit.argv);
+                    this.write(socket, { version: 1, id: request.id, ok: true, result });
+                    return;
+                }
+                case 'fleet_audit_finish': {
+                    if (!this.fleetAuditor)
+                        throw new SessionControlError('rejected', 'fleet auditing is unavailable');
+                    try {
+                        validateFleetAuditFinish(request.audit);
+                    }
+                    catch {
+                        throw new SessionControlError('rejected', 'valid fleet audit finish fields are required');
+                    }
+                    const audit = request.audit;
+                    const result = await this.fleetAuditor.finish({
+                        correlationId: audit.correlationId, class: audit.class, effect: audit.effect,
+                        ...(audit.exitCode === undefined ? {} : { exitCode: audit.exitCode }),
+                        ...(audit.resourceIds ? { resourceIds: audit.resourceIds } : {}),
+                        ...(audit.presentations ? { presentations: audit.presentations } : {}),
+                    });
+                    this.write(socket, { version: 1, id: request.id, ok: true, result });
+                    return;
+                }
                 case 'owner_channel_manage': {
                     if (!request.ownerChannel || typeof request.ownerChannel.action !== 'string')
                         throw new SessionControlError('rejected', 'owner-channel management action is required');

package/dist/session/types.d.ts

@@ -96,7 +96,7 @@ export interface InterruptOutcome {
     reasonCode?: string;
 }
 /**
- * What a `SessionHandle.interrupt` implementation may resolve. Before 0.17.1 the
+ * What an `AgentSession.interrupt` implementation may resolve. Before 0.17.1 the
  * contract was `Promise<void>`, and resolving at all meant the cancellation had
  * taken effect cooperatively — so an implementation written against that
  * contract stays valid and keeps its exact meaning. Only in-tree consumers read
@@ -146,7 +146,7 @@ export interface ExitRecord {
     code?: number;
     /** Signal that killed it, when one did. */
     signal?: string;
-    /** Raw wait status as the pane shell saw it (tmux only). */
+    /** Raw wait status retained when migrating a legacy shell-exit record. */
     status?: number;
     at?: string;
     /** One line an operator can read. */
@@ -194,8 +194,7 @@ export interface SessionSnapshot {
     };
     /**
      * Observed agent activity, independent of turn occupancy: the evidence a
-     * human-facing surface needs before calling a role idle. Absent on backends
-     * that cannot observe the agent at all (tmux), which is itself honest — no
+     * human-facing surface needs before calling a role idle. When absent, no
      * evidence is not evidence of inactivity.
      */
     activity?: SessionActivity;
@@ -259,7 +258,12 @@ export interface ConversationHandlePage {
     hasMore: boolean;
     snapshot: ConversationSnapshot;
 }
-export interface SessionHandle {
+/**
+ * The live, harness-neutral contract between Fleet and one agent session.
+ * Harness adapters construct this handle; orchestration code must not depend
+ * on the ACP transport which currently implements it.
+ */
+export interface AgentSession {
     readonly backend: SessionBackendId;
     readonly pid: number;
     isAlive(): boolean;
@@ -301,3 +305,5 @@ export interface SessionHandle {
     exitResult(): ExitRecord | null;
     close(): Promise<void>;
 }
+/** @deprecated Public compatibility name; use AgentSession. */
+export type SessionHandle = AgentSession;

package/dist/spawn.d.ts

@@ -1,5 +1,5 @@
 import type { IsolationConfig } from './isolation/types.js';
-import { type ApprovalMode, type FilesystemMode, type ResolvedRole, type RoleConfig, type MonitorConfig, type SessionBackendId, type UnattendedMode, type RoomMemberStartup } from './config.js';
+import { type ApprovalMode, type FilesystemMode, type ResolvedRole, type MonitorConfig, type UnattendedMode, type RoomMemberStartup, type AgentDefinition, type AgentSelection } from './config.js';
 import { type OpsDeps } from './ops.js';
 import { type CreationDeps, type CreationProvenance } from './creation.js';
 import './harness/claude-code.js';
@@ -13,34 +13,18 @@ export declare let lastProvenance: CreationProvenance | undefined;
 export interface SpawnOpts {
     name: string;
     temp?: boolean;
-    harness?: string;
-    session?: SessionBackendId;
-    mission?: string;
-    missionFile?: string;
+    brain?: AgentSelection;
+    role?: AgentSelection;
+    /** Trusted canonical definition used by room provisioning; never a second schema. */
+    agentDefinition?: AgentDefinition;
     identity?: string;
     cwd?: string;
     coordinator?: string;
-    /** null explicitly selects the harness default; undefined retains normal fleet inheritance. */
-    model?: string | null;
-    permissionMode?: string;
     approval?: ApprovalMode;
     filesystem?: FilesystemMode;
     unattended?: UnattendedMode;
-    sandbox?: string;
-    profile?: string;
-    launcher?: string;
-    search?: boolean;
-    codexConfig?: Record<string, string | number | boolean>;
-    reasoningEffort?: string | null;
-    addDirs?: string[];
-    monitor?: boolean;
     /** Typed external monitor configuration used by trusted creation surfaces. */
     monitorConfig?: Partial<MonitorConfig>;
-    bioFile?: string;
-    personaFile?: string;
-    /** Inline profile values for trusted typed callers such as the local web service. */
-    bio?: string;
-    persona?: string;
     /** Internal, non-sensitive provenance correlation for typed presentation layers. */
     surface?: 'cli' | 'web' | 'agent';
     creationActionId?: string;
@@ -61,12 +45,7 @@ export interface SpawnOpts {
     dryRun?: boolean;
     json?: boolean;
 }
-export declare function profileValues(o: SpawnOpts): {
-    bio?: string;
-    persona?: string;
-};
-/** Pure option-to-role mapping shared by CLI and application services. */
-export declare function buildRoleConfig(o: SpawnOpts, defaultHarness?: string): RoleConfig;
+export declare function agentDefinitionFromSpawn(o: SpawnOpts): AgentDefinition;
 /**
  * Read and validate an `--isolation-file`. The file is the existing
  * `isolation:` mapping and nothing else — the same schema, the same validator
@@ -78,16 +57,12 @@ export declare function buildRoleConfig(o: SpawnOpts, defaultHarness?: string):
  */
 export declare function readIsolationFile(path: string): IsolationConfig;
 export declare function validateSpawnOpts(o: SpawnOpts): void;
-/** Read mission text without trimming or newline rewriting. */
-export declare function readMissionFile(path: string): string;
 /** The ours identity a spawn will bind: explicit, else the role name. */
 export declare const effectiveIdentity: (o: SpawnOpts) => string;
 export interface SpawnDryRun {
     schemaVersion: 1;
     warning: string;
-    roleDocument: {
-        roles: Record<string, RoleConfig>;
-    };
+    roleDocument: Record<string, unknown>;
     resolvedRole: ResolvedRole;
 }
 /**
@@ -95,7 +70,7 @@ export interface SpawnDryRun {
  * or writing state. Collision checks are necessarily a point-in-time snapshot.
  */
 export declare function spawnDryRun(o: SpawnOpts): SpawnDryRun;
-/** Permanent spawn: persist to ~/fleet.d/<Name>.yaml, then bring it up. */
+/** Permanent spawn: persist one bare Agent document under the selected v2 root. */
 export declare function spawnPermanent(o: SpawnOpts, deps: OpsDeps, creation?: CreationDeps): Promise<string>;
 export type { SupervisorLauncher } from './temp-lifecycle.js';
 /** Temp spawn: live state under ~/.ours-fleet/tmp, independent transient supervision. */

package/dist/spawn.js

@@ -2,98 +2,56 @@ import { spawn as spawnChild } from 'node:child_process';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse, stringify } from 'yaml';
-import { agentDir, fleetDDir } from './paths.js';
+import { agentDir, defaultConfigPath } from './paths.js';
 import { validateIsolationConfig } from './isolation/policy.js';
-import { loadConfig, resolveAuthProxy, resolveModelChain, resolveMonitorConfig, resolveOwnerChannelConfig, resolvePermissions, resolveRoleModel, resolveWorklogPolicy, validateMonitorConfig, } from './config.js';
-import { resolveRoleModelEnv } from './model-env.js';
+import { loadConfig, findRole, splitRootFor, validateMonitorConfig, } from './config.js';
 import { applyRole, up } from './ops.js';
 import { START_STAGGER_FILE } from './runner.js';
 import { buildProvenance, daemonIdentityProvisioner, ensureIdentity, provenanceOf, withCreationTransaction, writeProvenance, writeRoleFile, } from './creation.js';
 import { VERSION } from './version.js';
+import { recordGeneratedAgentSource } from './generated-agent-source.js';
 import './harness/claude-code.js';
 import './harness/codex.js';
-import { getAdapter } from './harness/registry.js';
 import { archiveTempState, makeTempSupervisorLauncher, prepareTempSupervisor, reclaimStaleTempState, } from './temp-lifecycle.js';
 /**
  * The provenance record written by the most recent spawn in this process, so
  * the CLI can print the same summary it persisted rather than rebuilding it.
  */
 export let lastProvenance;
-export function profileValues(o) {
-    if (o.bio !== undefined && o.bioFile)
-        throw new Error('bio and bioFile are mutually exclusive');
-    if (o.persona !== undefined && o.personaFile)
-        throw new Error('persona and personaFile are mutually exclusive');
+export function agentDefinitionFromSpawn(o) {
+    if (o.agentDefinition) {
+        if (o.brain !== undefined || o.role !== undefined || o.cwd !== undefined
+            || o.coordinator !== undefined || o.approval !== undefined || o.filesystem !== undefined
+            || o.unattended !== undefined || o.isolationFile !== undefined || o.monitorConfig !== undefined)
+            throw new Error('canonical agentDefinition conflicts with separate Agent fields');
+        const definition = structuredClone(o.agentDefinition);
+        if (o.identity)
+            definition.identity = o.identity;
+        return definition;
+    }
+    if (!o.role)
+        throw new Error('--role is required (declared ID or inline mapping)');
+    if (!o.brain)
+        throw new Error('--brain is required (declared ID or inline mapping)');
+    const permissions = o.approval || o.filesystem || o.unattended ? {
+        ...(o.approval ? { approval: o.approval } : {}),
+        ...(o.filesystem ? { filesystem: o.filesystem } : {}),
+        ...(o.unattended ? { unattended: o.unattended } : {}),
+    } : undefined;
     return {
-        bio: o.bio !== undefined ? o.bio.trim()
-            : o.bioFile ? readFileSync(o.bioFile, 'utf8').trim() : undefined,
-        persona: o.persona !== undefined ? o.persona.trim()
-            : o.personaFile ? readFileSync(o.personaFile, 'utf8').trim() : undefined,
+        role: structuredClone(o.role), brain: structuredClone(o.brain),
+        ...(o.identity ? { identity: o.identity } : {}),
+        ...(o.cwd ? { cwd: o.cwd } : {}),
+        ...(o.coordinator ? { coordinator: o.coordinator } : {}),
+        ...(permissions ? { permissions } : {}),
+        ...(o.isolationFile ? { isolation: readIsolationFile(o.isolationFile) } : {}),
+        ...(o.monitorConfig ? { monitor: structuredClone(o.monitorConfig) } : {}),
     };
 }
-/** Pure option-to-role mapping shared by CLI and application services. */
-export function buildRoleConfig(o, defaultHarness) {
-    const r = {};
-    if (o.harness)
-        r.harness = o.harness;
-    if (o.session)
-        r.session = o.session;
-    if (o.identity)
-        r.identity = o.identity;
-    if (o.cwd)
-        r.cwd = o.cwd;
-    if (o.coordinator)
-        r.coordinator = o.coordinator;
-    if (o.missionFile)
-        r.mission = readMissionFile(o.missionFile);
-    else if (o.mission !== undefined)
-        r.mission = o.mission;
-    if (o.model === null)
-        r.model = null;
-    else if (o.model?.trim())
-        r.model = o.model.trim();
-    const harness = o.harness ?? defaultHarness;
-    const harnessOptions = {};
-    if (o.permissionMode)
-        harnessOptions[harness === 'claude-code' ? 'permission_mode' : 'approval'] = o.permissionMode;
-    if (o.sandbox)
-        harnessOptions.sandbox = o.sandbox;
-    if (o.profile)
-        harnessOptions.profile = o.profile;
-    if (o.launcher)
-        harnessOptions.launcher = o.launcher;
-    if (o.search === true)
-        harnessOptions.search = true;
-    const codexConfig = { ...(o.codexConfig ?? {}) };
-    if (o.reasoningEffort && harness === 'codex')
-        codexConfig.model_reasoning_effort = o.reasoningEffort;
-    if (Object.keys(codexConfig).length)
-        harnessOptions.config = codexConfig;
-    if (o.reasoningEffort && harness === 'claude-code')
-        harnessOptions.effort = o.reasoningEffort;
-    if (o.addDirs?.length)
-        harnessOptions.add_dirs = o.addDirs;
-    if (o.monitor === true)
-        harnessOptions.monitor = true;
-    if (Object.keys(harnessOptions).length)
-        r.harness_options = harnessOptions;
-    if (o.approval || o.filesystem || o.unattended) {
-        r.permissions = {
-            ...(o.approval ? { approval: o.approval } : {}),
-            ...(o.filesystem ? { filesystem: o.filesystem } : {}),
-            ...(o.unattended ? { unattended: o.unattended } : {}),
-        };
-    }
-    const profile = profileValues(o);
-    if (profile.bio)
-        r.bio = profile.bio;
-    if (profile.persona)
-        r.persona = profile.persona;
-    if (o.isolationFile)
-        r.isolation = readIsolationFile(o.isolationFile);
-    if (o.monitorConfig)
-        r.monitor = { ...o.monitorConfig };
-    return r;
+function resolvedSpawn(o) {
+    const definition = agentDefinitionFromSpawn(o);
+    const cfg = loadConfig(o.configPath, { additionalAgent: { id: o.name, definition } });
+    return { definition, role: findRole(cfg, o.name) };
 }
 /**
  * Read and validate an `--isolation-file`. The file is the existing
@@ -121,10 +79,6 @@ export function readIsolationFile(path) {
     return cfg;
 }
 export function validateSpawnOpts(o) {
-    if (o.mission !== undefined && o.missionFile)
-        throw new Error('--mission and --mission-file are mutually exclusive');
-    if (o.session && !['tmux', 'acp'].includes(o.session))
-        throw new Error(`invalid --session '${o.session}'; allowed: tmux, acp`);
     if (o.approval && !['ask', 'auto', 'allow', 'deny'].includes(o.approval))
         throw new Error(`invalid --approval '${o.approval}'; allowed: ask, auto, allow (deprecated alias: deny)`);
     if (o.filesystem && !['read-only', 'workspace', 'unrestricted'].includes(o.filesystem))
@@ -135,23 +89,12 @@ export function validateSpawnOpts(o) {
         throw new Error(`invalid role name '${o.name}'`);
     if (o.identity && !/^[A-Za-z0-9_-]+$/.test(o.identity))
         throw new Error(`invalid identity name '${o.identity}'`);
-    if (o.model && (o.model.length > 128 || /[\0-\x1f\x7f]/.test(o.model)))
-        throw new Error('model must be printable and at most 128 characters');
     if (o.monitorConfig) {
         const problems = validateMonitorConfig(o.monitorConfig);
         if (problems.length)
             throw new Error(problems.join('; '));
     }
 }
-/** Read mission text without trimming or newline rewriting. */
-export function readMissionFile(path) {
-    try {
-        return readFileSync(path, 'utf8');
-    }
-    catch (e) {
-        throw new Error(`--mission-file ${path}: ${e.message}`);
-    }
-}
 /**
  * Reject names that are already USED. This is a precondition, not a claim: it
  * runs INSIDE the creation transaction, after both names are reserved, so the
@@ -180,62 +123,13 @@ export function spawnDryRun(o) {
     validateSpawnOpts(o);
     if (o.isolationFile)
         readIsolationFile(o.isolationFile);
-    if (o.missionFile)
-        readMissionFile(o.missionFile);
     assertNameFree(o);
-    const cfg = loadConfig(o.configPath);
-    const raw = buildRoleConfig(o, cfg.defaults.harness);
-    const harnessOptions = {
-        ...(cfg.defaults.harness_options ?? {}),
-        ...(raw.harness_options ?? {}),
-    };
-    const harness = raw.harness ?? cfg.defaults.harness ?? 'claude-code';
-    const defaultHarness = cfg.defaults.harness ?? 'claude-code';
-    const inheritsModelDefaults = harness === defaultHarness && raw.model !== null;
-    const authProxy = resolveAuthProxy(cfg.defaults.auth_proxy, raw.auth_proxy);
-    // One resolution for the environment and the model it pins (src/model-env.ts).
-    const modelEnv = resolveRoleModelEnv({
-        harness,
-        model: resolveRoleModel(raw.model, raw.harness, cfg.defaults),
-        modelWasExplicit: raw.model !== undefined,
-        defaultsEnv: (cfg.defaults.env ?? {}),
-        roleEnv: raw.env,
-        ...(authProxy ? { authProxyBaseUrl: authProxy.base_url } : {}),
-    });
-    const model = modelEnv.model;
-    const session = raw.session ?? cfg.defaults.session ?? 'tmux';
-    const resolvedRole = {
-        ...raw,
-        name: o.name,
-        sourceFile: o.temp ? '(temp dry-run)' : join(fleetDDir(), `${o.name}.yaml`),
-        harness,
-        session,
-        session_options: raw.session_options,
-        permissions: resolvePermissions(cfg.defaults.permissions, raw.permissions),
-        permissionsDeclared: raw.permissions !== undefined || cfg.defaults.permissions !== undefined,
-        identity: effectiveIdentity(o),
-        model,
-        model_chain: resolveModelChain(model, raw.model_chain ?? (inheritsModelDefaults
-            ? cfg.defaults.model_chain
-            : undefined)),
-        harness_options: Object.keys(harnessOptions).length ? harnessOptions : undefined,
-        isolation: raw.isolation ?? cfg.defaults.isolation,
-        monitor: resolveMonitorConfig(cfg.defaults.monitor, raw.monitor),
-        owner_channel: resolveOwnerChannelConfig(cfg.defaults.owner_channel, raw.owner_channel, session),
-        worklog: resolveWorklogPolicy(cfg.defaults.worklog, raw.worklog),
-        auth_proxy: authProxy,
-    };
-    resolvedRole.env = modelEnv.env;
-    const adapter = getAdapter(resolvedRole.harness);
-    if (resolvedRole.auth_proxy && resolvedRole.harness !== 'claude-code')
-        throw new Error('auth_proxy is supported only by claude-code');
-    const optionProblems = adapter.validateOptions(resolvedRole.harness_options, resolvedRole);
-    if (optionProblems.length)
-        throw new Error(optionProblems.map(problem => `${problem.path}: ${problem.message}`).join('; '));
+    const resolved = resolvedSpawn(o);
+    const resolvedRole = resolved.role;
     return {
         schemaVersion: 1,
         warning: 'collision checks are a snapshot; a real spawn reserves names atomically',
-        roleDocument: { roles: { [o.name]: raw } },
+        roleDocument: structuredClone(resolved.definition),
         resolvedRole,
     };
 }
@@ -251,22 +145,15 @@ function provenanceSettings(o, defaults) {
     const perms = (defaults.permissions ?? {});
     const callerDefaults = new Set(o.inheritedFromCaller ?? []);
     const tagged = (key, entry) => callerDefaults.has(key) ? { ...entry, source: 'caller-role' } : entry;
-    const explicitModel = typeof o.model === 'string' ? o.model.trim() : undefined;
-    const inheritedModel = resolveRoleModel(undefined, o.harness, defaults);
+    const selection = (value) => value && 'ref' in value ? `ref:${value.ref}` : value ? 'inline' : undefined;
     return {
-        harness: tagged('harness', provenanceOf(o.harness, defaults.harness, 'claude-code')),
-        session: tagged('session', provenanceOf(o.session, defaults.session, 'tmux')),
+        brain: tagged('brain', provenanceOf(selection(o.brain), undefined, undefined)),
+        role: tagged('role', provenanceOf(selection(o.role), undefined, undefined)),
         identity: o.identity
             ? { value: o.identity, source: 'cli' }
             : { value: o.name, source: 'built-in' }, // defaults to the role name
         cwd: tagged('cwd', provenanceOf(o.cwd, undefined, undefined)),
-        model: tagged('model', o.model === null
-            ? { value: undefined, source: 'cli' }
-            : explicitModel
-                ? { value: explicitModel, source: 'cli' }
-                : { value: inheritedModel, source: inheritedModel ? 'fleet-default' : 'built-in' }),
         coordinator: tagged('coordinator', provenanceOf(o.coordinator, undefined, undefined)),
-        permission_mode: provenanceOf(o.permissionMode, undefined, undefined),
         approval: tagged('approval', provenanceOf(o.approval, perms.approval, 'ask')),
         filesystem: tagged('filesystem', provenanceOf(o.filesystem, perms.filesystem, 'workspace')),
         unattended: tagged('unattended', provenanceOf(o.unattended, perms.unattended, 'deny')),
@@ -276,13 +163,12 @@ function provenanceSettings(o, defaults) {
         monitor: tagged('monitorConfig', provenanceOf(o.monitorConfig, defaults.monitor, { mode: 'fleet' })),
     };
 }
-/** Permanent spawn: persist to ~/fleet.d/<Name>.yaml, then bring it up. */
+/** Permanent spawn: persist one bare Agent document under the selected v2 root. */
 export async function spawnPermanent(o, deps, creation = {}) {
     validateSpawnOpts(o);
     if (o.isolationFile)
         readIsolationFile(o.isolationFile); // fail before reserving
-    if (o.missionFile)
-        readMissionFile(o.missionFile); // fail before reserving
+    const prepared = resolvedSpawn(o); // canonical validation before mutation
     // Reserve name and identity together before anything is written or started.
     // A loser of the race creates no config, state, or service.
     creation.onStage?.('reserving');
@@ -292,7 +178,7 @@ export async function spawnPermanent(o, deps, creation = {}) {
         // Establish the identity BEFORE the service is enabled, and record
         // what was actually guaranteed so the briefing can say something true.
         creation.onStage?.('checking_identity');
-        const guarantee = await ensureIdentity(effectiveIdentity(o), profileValues(o), creation.identityProvisioner ?? deps.identityProvisioner ?? daemonIdentityProvisioner(), deps.log);
+        const guarantee = await ensureIdentity(effectiveIdentity(o), { bio: prepared.role.bio, persona: prepared.role.persona }, creation.identityProvisioner ?? deps.identityProvisioner ?? daemonIdentityProvisioner(), deps.log);
         creation.onStage?.('checking_identity', {
             result: guarantee.evidence, guarantee: guarantee.state,
         });
@@ -305,12 +191,11 @@ export async function spawnPermanent(o, deps, creation = {}) {
                     await creation.identityProvisioner?.remove?.(effectiveIdentity(o));
                 },
             });
-        mkdirSync(fleetDDir(), { recursive: true });
+        const agentRoot = join(splitRootFor(o.configPath ?? defaultConfigPath()), 'agents');
+        mkdirSync(agentRoot, { recursive: true });
         creation.onStage?.('writing_role');
-        const file = join(fleetDDir(), `${o.name}.yaml`);
-        writeRoleFile(tx, file, stringify({
-            roles: { [o.name]: buildRoleConfig(o, cfg.defaults.harness) },
-        }));
+        const file = join(agentRoot, `${o.name}.yaml`);
+        writeRoleFile(tx, file, stringify(agentDefinitionFromSpawn(o)));
         // `up` materialises the state dir and registers the service. Journal the
         // dir before it exists so a failure leaves the name genuinely reusable
         // rather than blocked by a half-built directory.
@@ -341,6 +226,7 @@ export async function spawnPermanent(o, deps, creation = {}) {
         });
         mkdirSync(agentDir(o.name), { recursive: true });
         writeProvenance(agentDir(o.name), provenance);
+        recordGeneratedAgentSource(agentDir(o.name), o.configPath ?? defaultConfigPath(), file);
         creation.onStage?.('registering_supervisor');
         await up(loadConfig(o.configPath), [o.name], {
             ...deps,
@@ -378,8 +264,7 @@ export async function spawnTemp(o, binPath, launch = independentSupervisor, crea
     validateSpawnOpts(o);
     if (o.isolationFile)
         readIsolationFile(o.isolationFile); // fail before reserving
-    if (o.missionFile)
-        readMissionFile(o.missionFile); // fail before reserving
+    const prepared = resolvedSpawn(o); // canonical validation before mutation
     // Retire only supervisors whose recorded owner is definitively stopped. This
     // bounded pass keeps the active roster clean without deleting old evidence.
     await reclaimStaleTempState();
@@ -392,56 +277,14 @@ export async function spawnTemp(o, binPath, launch = independentSupervisor, crea
         creation.onStage?.('checking_identity', {
             result: 'unknown', guarantee: 'unverified',
         });
-        return spawnTempInner(o, binPath, launch, tx, creation.onStage);
+        return spawnTempInner(o, prepared.role, binPath, launch, tx, creation.onStage);
     }, creation);
 }
-async function spawnTempInner(o, binPath, launch, tx, onStage) {
+async function spawnTempInner(o, preparedRole, binPath, launch, tx, onStage) {
     const cfg = loadConfig(o.configPath);
-    const defaultHarness = cfg.defaults.harness;
-    const fromOpts = buildRoleConfig(o, defaultHarness);
-    const mergedHarnessOptions = {
-        ...(cfg.defaults.harness_options ?? {}),
-        ...(fromOpts.harness_options ?? {}),
-    };
-    const harness = o.harness ?? defaultHarness ?? 'claude-code';
-    const inheritsModelDefaults = harness === (defaultHarness ?? 'claude-code') && o.model !== null;
-    const tempAuthProxy = resolveAuthProxy(cfg.defaults.auth_proxy, fromOpts.auth_proxy);
-    // An explicitly requested --model must reach the child, not just the banner
-    // (src/model-env.ts).
-    const modelEnv = resolveRoleModelEnv({
-        harness,
-        model: resolveRoleModel(o.model, o.harness, cfg.defaults),
-        modelWasExplicit: o.model !== undefined,
-        defaultsEnv: (cfg.defaults.env ?? {}),
-        roleEnv: fromOpts.env,
-        ...(tempAuthProxy ? { authProxyBaseUrl: tempAuthProxy.base_url } : {}),
-    });
-    const model = modelEnv.model;
-    const session = o.session ?? cfg.defaults.session ?? 'tmux';
     const role = {
-        ...fromOpts, // includes `isolation` when --isolation-file was given
-        name: o.name,
-        harness,
-        session,
-        identity: o.identity ?? o.name,
-        model,
-        model_chain: resolveModelChain(model, fromOpts.model_chain ?? (inheritsModelDefaults
-            ? cfg.defaults.model_chain
-            : undefined)),
-        harness_options: Object.keys(mergedHarnessOptions).length ? mergedHarnessOptions : undefined,
-        permissions: resolvePermissions(cfg.defaults.permissions, fromOpts.permissions),
-        permissionsDeclared: fromOpts.permissions !== undefined || cfg.defaults.permissions !== undefined,
-        // Temp agents inherit the fleet-wide monitor defaults via the snapshot.
-        monitor: resolveMonitorConfig(cfg.defaults.monitor, fromOpts.monitor),
-        owner_channel: resolveOwnerChannelConfig(cfg.defaults.owner_channel, fromOpts.owner_channel, session),
-        worklog: resolveWorklogPolicy(cfg.defaults.worklog, fromOpts.worklog),
-        auth_proxy: tempAuthProxy,
-        sourceFile: '(temp)',
-        roomMemberStartup: o.roomMemberStartup,
+        ...preparedRole, sourceFile: '(temp)', loops: undefined, roomMemberStartup: o.roomMemberStartup,
     };
-    role.env = modelEnv.env;
-    if (role.auth_proxy && role.harness !== 'claude-code')
-        throw new Error('auth_proxy is supported only by claude-code');
     onStage?.('writing_role');
     const dir = applyRole(role, { temp: true, identityGuarantee: 'unverified' });
     const provenance = buildProvenance({
@@ -467,10 +310,7 @@ async function spawnTempInner(o, binPath, launch, tx, onStage) {
     if (cfg.startStaggerMs > 0)
         writeFileSync(join(dir, START_STAGGER_FILE), String(cfg.startStaggerMs));
     prepareTempSupervisor(dir, o.name);
-    // Run the supervisor independently — NOT inside a tmux session named <name>.
-    // `_run-temp` -> runOnce() creates AND kills the tmux session <name> for the
-    // agent itself; a supervisor sharing that session name would SIGHUP its own
-    // process before the agent ever launches. On a service-managed host the temp
+    // Run the supervisor independently. On a service-managed host the temp
     // runner gets its own transient unit/job, so stopping the coordinator's unit
     // cannot kill a live worker in the coordinator's cgroup.
     onStage?.('starting_temp');

package/dist/supervisor/none.d.ts

@@ -1,7 +1,7 @@
 import { type Exec } from '../exec.js';
 import type { SupervisorBackend } from './types.js';
 /**
- * No supervision: sessions are plain tmux, nothing survives a reboot and
+ * No service supervision: tmux contains the direct runner process, nothing survives a reboot and
  * nothing restarts on crash. Used for temp agents and CI tests
  * (OURS_FLEET_SUPERVISOR=none).
  */