@ours.network/fleet 0.17.9 → 0.17.10

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
-  "version": "0.17.9",
-  "buildId": "6f77d2fb4e88",
-  "commit": "94827734295ad22ecb6691c099e960413a322970",
+  "version": "0.17.10",
+  "buildId": "1b9e94d03b53",
+  "commit": "f9932f0a2c99b8352286a3c4588bdfb57eed08f1",
   "dirty": false,
-  "builtAt": "2026-08-19T09:41:14.713Z",
+  "builtAt": "2026-08-19T19:43:42.121Z",
   "capabilities": [
     "monitor.interrupt.after_tool"
   ]

package/dist/config.js

@@ -4,6 +4,7 @@ import { agentDir, defaultConfigPath, fleetDDir, home } from './paths.js';
 import { parseFleetDocument, } from './config-yaml.js';
 import { harnessRuntimeDir, resolveIsolation, validateIsolationConfig, } from './isolation/policy.js';
 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 { CAPABILITIES, CAP_MONITOR_INTERRUPT_AFTER_TOOL } from './capabilities.js';
@@ -217,17 +218,23 @@ export function loadConfig(configPath, options = {}) {
             const harness = r.harness ?? defaults.harness ?? 'claude-code';
             const defaultHarness = defaults.harness ?? 'claude-code';
             const inheritsModelDefaults = harness === defaultHarness && r.model !== null;
-            const model = resolveRoleModel(r.model, r.harness, defaults);
+            if (authProxy && harness !== 'claude-code')
+                throw new ConfigError(`${file}: role '${name}' auth_proxy is supported only by claude-code`);
+            // Environment and runtime model are resolved together so `model:` and the
+            // harness's model pin can never disagree (see src/model-env.ts).
+            const modelEnv = resolveRoleModelEnv({
+                harness,
+                model: resolveRoleModel(r.model, r.harness, defaults),
+                modelWasExplicit: r.model !== undefined,
+                defaultsEnv: (defaults.env ?? {}),
+                roleEnv: r.env,
+                ...(authProxy ? { authProxyBaseUrl: authProxy.base_url } : {}),
+            }, message => new ConfigError(`${file}: role '${name}' ${message}`));
+            const env = modelEnv.env;
+            const model = modelEnv.model;
             const modelChain = resolveModelChain(model, r.model_chain ?? (inheritsModelDefaults
                 ? defaults.model_chain
                 : undefined), file, name);
-            if (authProxy && harness !== 'claude-code')
-                throw new ConfigError(`${file}: role '${name}' auth_proxy is supported only by claude-code`);
-            const env = {
-                ...(defaults.env ?? {}),
-                ...(r.env ?? {}),
-                ...(authProxy ? { ANTHROPIC_BASE_URL: authProxy.base_url } : {}),
-            };
             roles.push({
                 ...r,
                 name,

package/dist/model-env.d.ts

@@ -0,0 +1,71 @@
+import type { ResolvedRole } from './config.js';
+/**
+ * Which environment variable a harness reads to pin the model it RUNS.
+ *
+ * This is not a convenience: for `claude-code` it is the only channel that
+ * reaches the ACP backend at all. `buildLaunch` (tmux) passes `--model`, but
+ * `buildAcpLaunch` launches the ACP adapter with no model argument, and that
+ * adapter resolves its model in this order — ANTHROPIC_MODEL, then
+ * `settings.model`, then a resumed session's live model, then its first
+ * catalogue entry. A role's declared model was therefore invisible to every
+ * ACP role, and a fleet-wide `defaults.env.ANTHROPIC_MODEL` silently outranked
+ * an explicitly requested one.
+ */
+export declare const MODEL_ENV_BY_HARNESS: Readonly<Record<string, string>>;
+/** The model-pin variable for a harness, or undefined if it pins no model by env. */
+export declare function modelEnvVar(harness: string | undefined): string | undefined;
+export interface RoleModelEnvInput {
+    harness: string;
+    /** Already resolved by `resolveRoleModel` — may come from the fleet default. */
+    model: string | undefined;
+    /** True when the role (or `--model`) named a model, including `model: null`. */
+    modelWasExplicit: boolean;
+    defaultsEnv?: Record<string, string>;
+    roleEnv?: Record<string, string>;
+    authProxyBaseUrl?: string;
+}
+export interface RoleModelEnv {
+    env: Record<string, string>;
+    /**
+     * The model the harness will actually run. Equal to `env[pin]` for a harness
+     * that pins by env, so anything reporting this value reports the runtime.
+     */
+    model: string | undefined;
+}
+/**
+ * Resolve a role's environment and its runtime model TOGETHER, so the two can
+ * never disagree.
+ *
+ * Precedence, highest first:
+ *   1. an explicit `model:` / `--model` on the role
+ *   2. the role's own `env:` pin
+ *   3. the fleet `defaults.model`
+ *   4. the fleet `defaults.env` pin
+ *
+ * Inheriting the fleet default remains correct when the role names no model
+ * (2, 3, 4); an explicitly named one wins (1). Where both are explicit and they
+ * disagree, there is no defensible winner, so this refuses rather than picking
+ * one silently — the silence is what let a day of "Fable" work run on Opus.
+ *
+ * `model: null` explicitly asks for no fleet-chosen model, so it also clears an
+ * inherited pin instead of leaving one in place to act as a hidden default.
+ */
+export declare function resolveRoleModelEnv(input: RoleModelEnvInput, describe?: (message: string) => Error): RoleModelEnv;
+/**
+ * The model a role will actually run, read back from the environment it was
+ * resolved with. Use this wherever a model is reported to a human.
+ */
+export declare function effectiveRoleModel(role: ResolvedRole): string | undefined;
+/**
+ * Move a role's env pin onto a new model. Anything that changes the model a
+ * role runs after resolution — model-chain recovery is the live example — must
+ * go through this, or it changes only the label.
+ */
+export declare function repinModelEnv(role: ResolvedRole, model: string | undefined): Record<string, string> | undefined;
+/**
+ * Last line of defence, at the exact point a child's environment is composed:
+ * refuse to launch a role whose child would run a model other than the one the
+ * role declares and the banner reports. A spawn that cannot keep those two in
+ * agreement must fail loudly, not start and be believed.
+ */
+export declare function assertModelPinReachesChild(role: ResolvedRole, childEnv: Record<string, string | undefined>): void;

package/dist/model-env.js

@@ -0,0 +1,106 @@
+/**
+ * Which environment variable a harness reads to pin the model it RUNS.
+ *
+ * This is not a convenience: for `claude-code` it is the only channel that
+ * reaches the ACP backend at all. `buildLaunch` (tmux) passes `--model`, but
+ * `buildAcpLaunch` launches the ACP adapter with no model argument, and that
+ * adapter resolves its model in this order — ANTHROPIC_MODEL, then
+ * `settings.model`, then a resumed session's live model, then its first
+ * catalogue entry. A role's declared model was therefore invisible to every
+ * ACP role, and a fleet-wide `defaults.env.ANTHROPIC_MODEL` silently outranked
+ * an explicitly requested one.
+ */
+export const MODEL_ENV_BY_HARNESS = {
+    'claude-code': 'ANTHROPIC_MODEL',
+};
+/** The model-pin variable for a harness, or undefined if it pins no model by env. */
+export function modelEnvVar(harness) {
+    return harness === undefined ? undefined : MODEL_ENV_BY_HARNESS[harness];
+}
+/**
+ * Resolve a role's environment and its runtime model TOGETHER, so the two can
+ * never disagree.
+ *
+ * Precedence, highest first:
+ *   1. an explicit `model:` / `--model` on the role
+ *   2. the role's own `env:` pin
+ *   3. the fleet `defaults.model`
+ *   4. the fleet `defaults.env` pin
+ *
+ * Inheriting the fleet default remains correct when the role names no model
+ * (2, 3, 4); an explicitly named one wins (1). Where both are explicit and they
+ * disagree, there is no defensible winner, so this refuses rather than picking
+ * one silently — the silence is what let a day of "Fable" work run on Opus.
+ *
+ * `model: null` explicitly asks for no fleet-chosen model, so it also clears an
+ * inherited pin instead of leaving one in place to act as a hidden default.
+ */
+export function resolveRoleModelEnv(input, describe = message => new Error(message)) {
+    const env = {
+        ...(input.defaultsEnv ?? {}),
+        ...(input.roleEnv ?? {}),
+        ...(input.authProxyBaseUrl ? { ANTHROPIC_BASE_URL: input.authProxyBaseUrl } : {}),
+    };
+    const pin = modelEnvVar(input.harness);
+    if (!pin)
+        return { env, model: input.model };
+    const rolePin = input.roleEnv?.[pin];
+    if (input.modelWasExplicit) {
+        if (rolePin !== undefined && rolePin !== input.model)
+            throw describe(`model '${input.model ?? '(none)'}' contradicts env.${pin} '${rolePin}'; `
+                + `remove one — ${pin} is what the harness actually runs`);
+        if (input.model === undefined)
+            delete env[pin];
+        else
+            env[pin] = input.model;
+        return { env, model: input.model };
+    }
+    // Not explicit: a role-level pin is the most specific thing said about this
+    // role, so it decides — and the reported model follows it.
+    if (rolePin !== undefined)
+        return { env, model: rolePin };
+    if (input.model !== undefined)
+        env[pin] = input.model;
+    return { env, model: input.model ?? env[pin] };
+}
+/**
+ * The model a role will actually run, read back from the environment it was
+ * resolved with. Use this wherever a model is reported to a human.
+ */
+export function effectiveRoleModel(role) {
+    const pin = modelEnvVar(role.harness);
+    return (pin ? role.env?.[pin] : undefined) ?? role.model;
+}
+/**
+ * Move a role's env pin onto a new model. Anything that changes the model a
+ * role runs after resolution — model-chain recovery is the live example — must
+ * go through this, or it changes only the label.
+ */
+export function repinModelEnv(role, model) {
+    const pin = modelEnvVar(role.harness);
+    if (!pin)
+        return role.env;
+    const env = { ...(role.env ?? {}) };
+    if (model === undefined)
+        delete env[pin];
+    else
+        env[pin] = model;
+    return Object.keys(env).length ? env : undefined;
+}
+/**
+ * Last line of defence, at the exact point a child's environment is composed:
+ * refuse to launch a role whose child would run a model other than the one the
+ * role declares and the banner reports. A spawn that cannot keep those two in
+ * agreement must fail loudly, not start and be believed.
+ */
+export function assertModelPinReachesChild(role, childEnv) {
+    const pin = modelEnvVar(role.harness);
+    if (!pin || role.model === undefined)
+        return;
+    const actual = childEnv[pin];
+    if (actual === role.model)
+        return;
+    throw new Error(`[${role.name}] refusing to launch: role model is '${role.model}' but the child's `
+        + `${pin} is ${actual === undefined ? 'unset' : `'${actual}'`} — the session would run a `
+        + 'different model than the one reported');
+}

package/dist/runner.d.ts

@@ -35,6 +35,15 @@ export interface RunnerDeps {
 }
 /** Environment injected only into the managed harness process. */
 export declare function managedFleetProxyEnv(role: ResolvedRole, stateDir: string): Record<string, string>;
+/**
+ * The environment a managed harness child actually receives, checked at the one
+ * point where it is composed. `role.env` deliberately wins over harness prep,
+ * which is exactly how a stale fleet-wide model pin used to outrank the model
+ * the role was spawned with — so the model pin is verified here rather than
+ * trusted, and a disagreement stops the launch instead of being reported as a
+ * success (see src/model-env.ts).
+ */
+export declare function harnessChildEnv(role: ResolvedRole, launchEnv: Record<string, string> | undefined, stateDir: string): Record<string, string>;
 /**
  * Record who owns wake delivery for this run. Returning true means a fleet
  * monitor is taking ownership back from a native harness and must start at the

package/dist/runner.js

@@ -24,6 +24,7 @@ import { RoleTurnArbiter } from './session/arbiter.js';
 import { ScheduledLoopManager, } from './loops/manager.js';
 import { FLEET_PROXY_CALLER_ENV, FLEET_PROXY_STATE_DIR_ENV, inheritCallerSpawnDefaults, } from './fleet-proxy.js';
 import { effectivePermissionMode } from './permissions.js';
+import { assertModelPinReachesChild, effectiveRoleModel, repinModelEnv } from './model-env.js';
 import { archiveTempState, markTempSupervisorActive, requestedTempStopReason, } from './temp-lifecycle.js';
 const defaultDeps = () => ({
     tmux: new Tmux(),
@@ -72,6 +73,19 @@ export function managedFleetProxyEnv(role, stateDir) {
         [FLEET_PROXY_CALLER_ENV]: role.name,
     };
 }
+/**
+ * The environment a managed harness child actually receives, checked at the one
+ * point where it is composed. `role.env` deliberately wins over harness prep,
+ * which is exactly how a stale fleet-wide model pin used to outrank the model
+ * the role was spawned with — so the model pin is verified here rather than
+ * trusted, and a disagreement stops the launch instead of being reported as a
+ * success (see src/model-env.ts).
+ */
+export function harnessChildEnv(role, launchEnv, stateDir) {
+    const env = { ...(launchEnv ?? {}), ...managedFleetProxyEnv(role, stateDir) };
+    assertModelPinReachesChild(role, env);
+    return env;
+}
 /**
  * Execute a typed proxy request in the caller's supervisor. Dynamic imports
  * avoid a runner↔spawn initialization cycle (spawn imports runner constants).
@@ -109,7 +123,9 @@ async function executeManagedSpawn(caller, configPath, requested, log) {
         statePath,
         harness: preview.harness,
         session: preview.session,
-        ...(preview.model ? { model: preview.model } : {}),
+        // Read back from the resolved environment, not from the request: the banner
+        // must name the model the child will run, not the one that was asked for.
+        ...(effectiveRoleModel(preview) ? { model: effectiveRoleModel(preview) } : {}),
         monitor: { mode: preview.monitor.mode, interrupt: preview.monitor.interrupt },
         permissionMode: effectivePermissionMode(preview),
         inherited,
@@ -117,6 +133,7 @@ async function executeManagedSpawn(caller, configPath, requested, log) {
     };
     log(`[${caller.name}] managed fleet proxy spawned ${result.lifetime} role ${result.role} `
         + `harness=${result.harness} session=${result.session} `
+        + `model=${result.model ?? '(harness default)'} `
         + `permission=${result.permissionMode.fleetMode} `
         + `native=${result.permissionMode.nativeMode}`);
     return result;
@@ -458,11 +475,18 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     const effectiveModel = effectiveModelForRole(dir, role);
     if (effectiveModel !== role.model) {
         deps.log(`[${name}] model recovery drift: declared=${role.model ?? '(none)'} effective=${effectiveModel}`);
-        role = { ...role, model: effectiveModel };
+        // The env pin has to move with it. A down-shift that changed only
+        // `role.model` was reported as a model change while the child kept running
+        // the model that had just failed, because the pin is what the harness reads.
+        role = { ...role, model: effectiveModel, env: repinModelEnv(role, effectiveModel) };
     }
     if (modelRecoveryHeld(dir))
         throw new Error(`[${name}] model chain exhausted — held down until config changes or recovery reset`);
     const adapter = getAdapter(role.harness);
+    // Say the running model out loud, once, from the resolved environment. The
+    // spawn banner is a claim made before the process exists; this is the log line
+    // that can be checked against the session afterwards.
+    deps.log(`[${name}] model: ${effectiveRoleModel(role) ?? '(harness default)'}`);
     mkdirSync(dir, { recursive: true });
     const rotation = rotateWorklog(join(dir, 'WORKLOG.md'), role.worklog);
     if (rotation.deferred)
@@ -603,7 +627,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
             name,
             argv: wrappedArgv,
             cwd: runCwd,
-            env: { ...launch.env, ...managedFleetProxyEnv(role, dir) },
+            env: harnessChildEnv(role, launch.env, dir),
             stateDir: dir,
             mode,
             permissions: perms,

package/dist/spawn.js

@@ -5,6 +5,7 @@ import { parse, stringify } from 'yaml';
 import { agentDir, fleetDDir } 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 { applyRole, up } from './ops.js';
 import { START_STAGGER_FILE } from './runner.js';
 import { buildProvenance, daemonIdentityProvisioner, ensureIdentity, provenanceOf, withCreationTransaction, writeProvenance, writeRoleFile, } from './creation.js';
@@ -191,7 +192,17 @@ export function spawnDryRun(o) {
     const harness = raw.harness ?? cfg.defaults.harness ?? 'claude-code';
     const defaultHarness = cfg.defaults.harness ?? 'claude-code';
     const inheritsModelDefaults = harness === defaultHarness && raw.model !== null;
-    const model = resolveRoleModel(raw.model, raw.harness, cfg.defaults);
+    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,
@@ -212,15 +223,9 @@ export function spawnDryRun(o) {
         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: resolveAuthProxy(cfg.defaults.auth_proxy, raw.auth_proxy),
-    };
-    resolvedRole.env = {
-        ...(cfg.defaults.env ?? {}),
-        ...(raw.env ?? {}),
-        ...(resolvedRole.auth_proxy
-            ? { ANTHROPIC_BASE_URL: resolvedRole.auth_proxy.base_url }
-            : {}),
+        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');
@@ -403,7 +408,18 @@ async function spawnTempInner(o, binPath, launch, tx, guarantee, onStage) {
     };
     const harness = o.harness ?? defaultHarness ?? 'claude-code';
     const inheritsModelDefaults = harness === (defaultHarness ?? 'claude-code') && o.model !== null;
-    const model = resolveRoleModel(o.model, o.harness, cfg.defaults);
+    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
@@ -422,14 +438,10 @@ async function spawnTempInner(o, binPath, launch, tx, guarantee, onStage) {
         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: resolveAuthProxy(cfg.defaults.auth_proxy, fromOpts.auth_proxy),
+        auth_proxy: tempAuthProxy,
         sourceFile: '(temp)',
     };
-    role.env = {
-        ...(cfg.defaults.env ?? {}),
-        ...(fromOpts.env ?? {}),
-        ...(role.auth_proxy ? { ANTHROPIC_BASE_URL: role.auth_proxy.base_url } : {}),
-    };
+    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');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet",
-  "version": "0.17.9",
+  "version": "0.17.10",
   "description": "Harness-agnostic fleet of persistent, identity-bound AI agents. Declarative fleet.yaml, tmux or ACP sessions, supervision, and ours.network messaging.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",