@ours.network/fleet 0.19.0-nightly.8 → 1.0.0

package/dist/session/activity.js

@@ -0,0 +1,48 @@
+/**
+ * How long after the agent's last session update it still counts as working.
+ *
+ * FLEET-002: a wake delivered by ACP steering answers `startedNewTurn` and runs
+ * an entire turn that fleet never receives a `session/prompt` response for (ACP
+ * has no turn-end session update), so `readiness` stays `idle` throughout. Tool
+ * reservations and update recency are the only activity evidence fleet holds.
+ * The trade-off is deliberate and one-directional: at worst a role reads busy
+ * for one window after it genuinely stopped, instead of reading ready — or
+ * being classified stalled — while it is executing tools.
+ */
+export const ACTIVITY_WINDOW_MS = 60_000;
+/**
+ * Classify agent-side activity. `unobservable` is NOT `quiet`: a backend that
+ * cannot see the agent (tmux) has no evidence, and no evidence must never be
+ * reported as "doing nothing".
+ */
+export function classifyActivity(activity, now = Date.now()) {
+    if (!activity)
+        return { state: 'unobservable' };
+    const lastUpdate = activity.lastUpdateAt ? Date.parse(activity.lastUpdateAt) : NaN;
+    const recent = Number.isFinite(lastUpdate) && now - lastUpdate <= ACTIVITY_WINDOW_MS;
+    return {
+        state: activity.activeToolCalls > 0 || recent ? 'active' : 'quiet',
+        activeToolCalls: activity.activeToolCalls,
+        ...(activity.lastUpdateAt ? { lastUpdateAt: activity.lastUpdateAt } : {}),
+    };
+}
+/**
+ * One operator-facing line that never lets turn occupancy pose as liveness:
+ * the readiness value is labelled as the turn field it is, and the activity
+ * verdict is stated separately with the evidence behind it.
+ */
+export function describeSessionState(readiness, activity, now = Date.now()) {
+    const observed = classifyActivity(activity, now);
+    const evidence = [];
+    if (observed.activeToolCalls)
+        evidence.push(`${observed.activeToolCalls} tool calls in flight`);
+    if (observed.lastUpdateAt) {
+        const age = Math.max(0, Math.round((now - Date.parse(observed.lastUpdateAt)) / 1000));
+        if (Number.isFinite(age))
+            evidence.push(`last agent update ${age}s ago`);
+    }
+    const detail = observed.state === 'unobservable'
+        ? 'no agent-side evidence on this backend'
+        : evidence.join(', ') || 'no updates yet';
+    return `turn: ${readiness ?? 'unknown'} (turn occupancy only) | activity: ${observed.state} (${detail})`;
+}

package/dist/session/control.d.ts

@@ -47,7 +47,7 @@ export interface ControlResponse {
  */
 export declare function livenessNote(kind: ControlFailureKind, name: string): string;
 /**
- * The result taxonomy an overseer judges a role by (7.2).
+ * The result taxonomy an overseer judges a role by.
  *
  * One console command is not a liveness verdict. `peek` and `send` can fail for
  * five distinct reasons and succeed for one, and only ONE of the six says the

package/dist/session/conversation-normalizer.d.ts

@@ -9,8 +9,14 @@ import type { AdapterMeta, ConversationEventKind, ConversationPayload } from './
  * and quarantines namespaced `_meta` so unknown extensions cannot leak into
  * generic rendering paths.
  */
-/** Cap for any single normalized text payload (spec §5.3). */
+/** Cap for any single normalized text payload. */
 export declare const MAX_TEXT_BYTES: number;
+/** Cap for each retained side of an oversized snapshot-style file diff. */
+export declare const MAX_DIFF_TEXT_BYTES: number;
+/** Cap for attacker-controlled filesystem paths while retaining their useful basename tail. */
+export declare const MAX_PATH_BYTES: number;
+/** Hard cap for the complete normalized update before the durable event envelope is added. */
+export declare const MAX_NORMALIZED_UPDATE_BYTES: number;
 /** Cap for one adapter `_meta` namespace value. */
 export declare const MAX_META_BYTES: number;
 /** Cap for serialized raw tool input/output retained as structured JSON. */

package/dist/session/conversation-normalizer.js

@@ -8,8 +8,14 @@ import { createHash } from 'node:crypto';
  * and quarantines namespaced `_meta` so unknown extensions cannot leak into
  * generic rendering paths.
  */
-/** Cap for any single normalized text payload (spec §5.3). */
+/** Cap for any single normalized text payload. */
 export const MAX_TEXT_BYTES = 256 * 1024;
+/** Cap for each retained side of an oversized snapshot-style file diff. */
+export const MAX_DIFF_TEXT_BYTES = 64 * 1024;
+/** Cap for attacker-controlled filesystem paths while retaining their useful basename tail. */
+export const MAX_PATH_BYTES = 4 * 1024;
+/** Hard cap for the complete normalized update before the durable event envelope is added. */
+export const MAX_NORMALIZED_UPDATE_BYTES = 320 * 1024;
 /** Cap for one adapter `_meta` namespace value. */
 export const MAX_META_BYTES = 16 * 1024;
 /** Cap for serialized raw tool input/output retained as structured JSON. */
@@ -27,6 +33,28 @@ function truncateUtf8(text, maxBytes) {
     const buffer = Buffer.from(text).subarray(0, maxBytes);
     return buffer.toString('utf8').replace(/�+$/u, '');
 }
+/** Keep a UTF-8-safe suffix. Paths and identifiers have no line semantics. */
+function truncateUtf8Tail(text, maxBytes) {
+    const buffer = Buffer.from(text);
+    let start = Math.max(0, buffer.length - maxBytes);
+    while (start < buffer.length && (buffer[start] & 0xc0) === 0x80)
+        start++;
+    return { text: buffer.subarray(start).toString('utf8'), omittedPrefixBytes: start };
+}
+function boundedPath(raw) {
+    const path = asString(raw) ?? '';
+    const pathBytes = Buffer.byteLength(path);
+    if (pathBytes <= MAX_PATH_BYTES)
+        return { path };
+    const retained = truncateUtf8Tail(path, MAX_PATH_BYTES);
+    return {
+        path: retained.text,
+        pathBytes,
+        pathTruncated: true,
+        pathDigest: digest24(path),
+        pathOmittedPrefixBytes: retained.omittedPrefixBytes,
+    };
+}
 function cappedText(raw, redact) {
     const text = asString(raw) ?? '';
     const bytes = Buffer.byteLength(text);
@@ -39,6 +67,95 @@ function cappedText(raw, redact) {
         truncated: true, digest: digest24(text),
     };
 }
+/** Keep the newest UTF-8 tail, aligning to a whole line whenever one fits. */
+function cappedTextTail(text, maxBytes) {
+    const buffer = Buffer.from(text);
+    const bytes = buffer.length;
+    if (bytes <= maxBytes)
+        return { text, bytes };
+    let start = bytes - maxBytes;
+    while (start < bytes && (buffer[start] & 0xc0) === 0x80)
+        start++;
+    let startsMidLine = start > 0 && buffer[start - 1] !== 0x0a;
+    if (startsMidLine) {
+        const newline = buffer.indexOf(0x0a, start);
+        if (newline >= 0 && newline + 1 < bytes) {
+            start = newline + 1;
+            startsMidLine = false;
+        }
+    }
+    return {
+        text: buffer.subarray(start).toString('utf8'), bytes,
+        truncated: true, digest: digest24(text), omittedPrefixBytes: start,
+        ...(startsMidLine ? { startsMidLine: true } : {}),
+    };
+}
+/** Common unchanged edges in UTF-16 indices, adjusted away from split surrogates. */
+function commonEdges(oldText, newText) {
+    const limit = Math.min(oldText.length, newText.length);
+    let prefix = 0;
+    while (prefix < limit && oldText.charCodeAt(prefix) === newText.charCodeAt(prefix))
+        prefix++;
+    if (prefix > 0 && prefix < limit
+        && oldText.charCodeAt(prefix) >= 0xdc00 && oldText.charCodeAt(prefix) <= 0xdfff)
+        prefix--;
+    let oldEnd = oldText.length;
+    let newEnd = newText.length;
+    while (oldEnd > prefix && newEnd > prefix
+        && oldText.charCodeAt(oldEnd - 1) === newText.charCodeAt(newEnd - 1)) {
+        oldEnd--;
+        newEnd--;
+    }
+    // A suffix must never begin at the low half of a surrogate pair.
+    if (oldEnd < oldText.length && oldText.charCodeAt(oldEnd) >= 0xdc00
+        && oldText.charCodeAt(oldEnd) <= 0xdfff) {
+        oldEnd++;
+        newEnd++;
+    }
+    return { prefix, suffix: oldText.length - oldEnd };
+}
+function normalizedDiff(item, redact) {
+    const path = boundedPath(item.path);
+    const oldText = asString(item.oldText);
+    const newText = asString(item.newText) ?? '';
+    // Preserve the established small-diff contract exactly. Redacted turns also
+    // retain their established placeholder shape and never derive private text.
+    if (redact !== undefined || oldText === undefined
+        || (Buffer.byteLength(oldText) <= MAX_TEXT_BYTES
+            && Buffer.byteLength(newText) <= MAX_TEXT_BYTES)) {
+        return {
+            type: 'diff', ...path,
+            newText: cappedText(newText, redact),
+            ...(oldText !== undefined ? { oldText: cappedText(oldText, redact) } : {}),
+        };
+    }
+    // ACP adapters may describe an append by sending two complete file snapshots.
+    // Persist only the changed region: otherwise a multi-megabyte historical file
+    // contributes its prefix twice while the current append disappears past the cap.
+    const { prefix, suffix } = commonEdges(oldText, newText);
+    const oldEnd = oldText.length - suffix;
+    const newEnd = newText.length - suffix;
+    const oldDelta = oldText.slice(prefix, oldEnd);
+    const newDelta = newText.slice(prefix, newEnd);
+    const beforeBytes = Buffer.byteLength(oldText);
+    const afterBytes = Buffer.byteLength(newText);
+    const commonPrefixBytes = Buffer.byteLength(oldText.slice(0, prefix));
+    const commonSuffixBytes = Buffer.byteLength(oldText.slice(oldEnd));
+    const operation = oldDelta.length === 0 && newDelta.length === 0
+        ? 'noop'
+        : oldDelta.length === 0 && prefix === oldText.length
+            ? 'append'
+            : newDelta.length === 0
+                ? 'delete'
+                : prefix === 0 && suffix === 0 ? 'replace' : 'edit';
+    return {
+        type: 'diff', ...path, operation, beforeBytes, afterBytes,
+        commonPrefixBytes, commonSuffixBytes, bounded: true,
+        newText: cappedTextTail(newDelta, MAX_DIFF_TEXT_BYTES),
+        ...(oldDelta.length > 0
+            ? { oldText: cappedTextTail(oldDelta, MAX_DIFF_TEXT_BYTES) } : {}),
+    };
+}
 function normalizedText(raw, redact) {
     const text = asString(raw) ?? '';
     const bytes = Buffer.byteLength(text);
@@ -189,12 +306,7 @@ function normalizeToolContent(raw, redact) {
     return raw.filter(isRecord).map((item) => {
         switch (item.type) {
             case 'diff':
-                return {
-                    type: 'diff',
-                    path: asString(item.path) ?? '',
-                    newText: cappedText(item.newText, redact),
-                    ...(item.oldText != null ? { oldText: cappedText(item.oldText, redact) } : {}),
-                };
+                return normalizedDiff(item, redact);
             case 'terminal':
                 return { type: 'terminal', terminalId: asString(item.terminalId) ?? '' };
             case 'content':
@@ -220,7 +332,7 @@ function toolUpsert(update, snapshot, options) {
         payload.content = content;
     if (Array.isArray(update.locations)) {
         payload.locations = update.locations.filter(isRecord).map(location => ({
-            path: asString(location.path) ?? '',
+            ...boundedPath(location.path),
             ...(asFiniteNumber(location.line) !== undefined ? { line: asFiniteNumber(location.line) } : {}),
         }));
     }
@@ -240,18 +352,49 @@ function unsupported(update) {
     }
     const kind = isRecord(update) ? asString(update.sessionUpdate) : undefined;
     return {
-        sessionUpdate: kind ?? 'unknown',
+        sessionUpdate: truncateUtf8(kind ?? 'unknown', 256),
         bytes: Buffer.byteLength(serialized),
         preview: serialized.slice(0, MAX_UNSUPPORTED_PREVIEW_CHARS),
+        ...(Buffer.byteLength(serialized) > Buffer.byteLength(serialized.slice(0, MAX_UNSUPPORTED_PREVIEW_CHARS))
+            ? { digest: digest24(serialized) } : {}),
+    };
+}
+function capNormalizedUpdate(result, sessionUpdate) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(result);
+    }
+    catch {
+        return {
+            kind: 'unsupported',
+            payload: {
+                sessionUpdate: truncateUtf8(sessionUpdate, 256),
+                bytes: 0,
+                preview: '[normalized update was not serializable]',
+            },
+        };
+    }
+    const bytes = Buffer.byteLength(serialized);
+    if (bytes <= MAX_NORMALIZED_UPDATE_BYTES)
+        return result;
+    return {
+        kind: 'unsupported',
+        payload: {
+            sessionUpdate: truncateUtf8(sessionUpdate, 256),
+            bytes,
+            digest: digest24(serialized),
+            preview: `[normalized update exceeded ${MAX_NORMALIZED_UPDATE_BYTES}-byte durable-event cap]`,
+        },
     };
 }
 export function normalizeSessionUpdate(update, options = {}) {
     const redact = options.redactText;
     const raw = update;
     if (!isRecord(raw) || typeof raw.sessionUpdate !== 'string')
-        return { kind: 'unsupported', payload: unsupported(raw) };
+        return capNormalizedUpdate({ kind: 'unsupported', payload: unsupported(raw) }, 'unknown');
+    const sessionUpdate = raw.sessionUpdate;
     const adapterMeta = quarantineMeta(raw._meta);
-    const withMeta = (result) => adapterMeta ? { ...result, adapterMeta } : result;
+    const withMeta = (result) => capNormalizedUpdate(adapterMeta ? { ...result, adapterMeta } : result, sessionUpdate);
     switch (raw.sessionUpdate) {
         case 'user_message_chunk':
         case 'agent_message_chunk': {

package/dist/session/conversation-store.js

@@ -3,7 +3,7 @@ import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, re
 import { join } from 'node:path';
 /**
  * Durable, append-only, single-writer conversation ledger for one role
- * (spec §5.3). The per-role runner is the only writer; readers page by seq.
+ * The per-role runner is the only writer; readers page by seq.
  *
  * Unlike `SessionEvents` (a bounded diagnostic projection that may drop
  * writes silently), this store is the transcript of record: an acknowledged

package/dist/session/conversation-types.d.ts

@@ -1,11 +1,11 @@
 import type { PromptOrigin, TurnCancellationSource, TurnOutcome } from './types.js';
 /**
- * Durable conversation domain schema (ACP web console, spec §5.2).
+ * Durable conversation domain schema for the ACP web console.
  *
  * `SessionEvent` in ./types.js remains the compact diagnostic projection; the
  * types here describe the durable per-role conversation ledger. Nothing in this
  * file touches the wire: ACP updates are reduced into these shapes by the
- * normalizer, and the store (phase 1) assigns `seq`/`eventId`/timestamps.
+ * normalizer, and the store assigns `seq`/`eventId`/timestamps.
  */
 export type ConversationEventKind = 'prompt.admitted' | 'prompt.started' | 'prompt.interrupt_requested' | 'message.chunk' | 'message.replace' | 'thought.chunk' | 'thought.replace' | 'plan.replace' | 'tool.upsert' | 'tool.content_chunk' | 'permission.requested' | 'permission.resolved' | 'monitor.delivery' | 'usage.updated' | 'turn.state' | 'turn.completed' | 'session.state' | 'session.info' | 'capabilities.updated' | 'error'
 /** A well-formed ACP update this version cannot represent. Bounded, never a crash. */
@@ -48,15 +48,33 @@ export interface CappedText {
     bytes: number;
     truncated?: true;
     digest?: string;
+    /** Bytes omitted from the front when the retained fragment is a tail. */
+    omittedPrefixBytes?: number;
+    /** The retained tail starts inside one logical line because that line alone exceeded the cap. */
+    startsMidLine?: true;
+}
+/** A path kept as a UTF-8-safe tail, with additive provenance only when capped. */
+export interface BoundedPath {
+    path: string;
+    pathBytes?: number;
+    pathTruncated?: true;
+    pathDigest?: string;
+    pathOmittedPrefixBytes?: number;
 }
 export type NormalizedToolContent = {
     type: 'content';
     content: NormalizedContentBlock;
-} | {
+} | BoundedPath & {
     type: 'diff';
-    path: string;
     newText: CappedText;
     oldText?: CappedText;
+    /** Additive provenance for oversized snapshot diffs reduced to their changed region. */
+    operation?: 'append' | 'edit' | 'delete' | 'noop' | 'replace';
+    beforeBytes?: number;
+    afterBytes?: number;
+    commonPrefixBytes?: number;
+    commonSuffixBytes?: number;
+    bounded?: true;
 }
 /** A tool-owned display terminal reference — never a PTY attachment. */
  | {
@@ -105,8 +123,7 @@ export interface ToolUpsertPayload {
     kind?: string;
     status?: string;
     content?: NormalizedToolContent[];
-    locations?: Array<{
-        path: string;
+    locations?: Array<BoundedPath & {
         line?: number;
     }>;
     rawInput?: BoundedJson;
@@ -140,6 +157,8 @@ export interface UnsupportedPayload {
     /** The wire discriminant (or 'unknown' when even that was absent). */
     sessionUpdate: string;
     bytes: number;
+    /** Digest of the omitted original/normalized representation when it was bounded. */
+    digest?: string;
     /** Sanitized JSON preview, capped; enough to diagnose, never to exhaust. */
     preview?: string;
 }

package/dist/session/types.d.ts

@@ -1,5 +1,16 @@
 import type { SessionBackendId } from '../config.js';
 import type { ConversationEventV1, ConversationSnapshot, PromptReceipt, SubmitPromptCommand } from './conversation-types.js';
+/**
+ * TURN OCCUPANCY, and nothing else: `idle` means no fleet-tracked turn is in
+ * flight, which is exactly the question `arbiter.tryScheduled` asks before it
+ * admits a prompt. It is NOT a claim that the agent is doing nothing — a wake
+ * delivered through the `_session/steering` extension answers `startedNewTurn`
+ * and runs a whole turn that fleet never gets a `session/prompt` response for
+ * (ACP has no turn-end session update), so `readiness` stays `idle` for its
+ * entire duration. Anything reporting activity or liveness to a human must
+ * corroborate with `SessionSnapshot.activity` instead of reading `idle` here as
+ * "not working".
+ */
 export type SessionReadiness = 'starting' | 'idle' | 'running' | 'awaiting_permission' | 'failed';
 export type TurnOutcome = 'completed' | 'refused' | 'cancelled' | 'failed' | 'inconclusive';
 export type TurnCancellationSource = 'owner' | 'local-console' | 'fleet-monitor' | 'scheduled-loop' | 'shutdown';
@@ -99,6 +110,15 @@ export declare function interruptOutcome(result: InterruptResult): InterruptOutc
  * stop here: the session has the prompt, and waiting for the turn to finish is
  * a different question with a different, much longer, timescale.
  */
+/**
+ * What actually happened to an admitted prompt, so a caller reporting to a
+ * human can be accurate instead of repeating what it asked for.
+ *
+ * `interrupted` is only ever returned when a turn was really cancelled for this
+ * prompt. `deferred` says the session is busy with work this prompt could not
+ * safely pre-empt — the prompt is admitted and will run, just not yet.
+ */
+export type PromptDelivery = 'started' | 'queued' | 'interrupted' | 'deferred';
 export interface QueuedPrompt {
     promptId: string;
     /** Turns already queued ahead of this one. 0 means it starts immediately. */
@@ -106,6 +126,8 @@ export interface QueuedPrompt {
     origin?: PromptOrigin;
     /** The turn's terminal result. Never rejects. */
     completion: Promise<TurnResult>;
+    /** Observed admission outcome. Absent on backends that do not report it. */
+    delivery?: PromptDelivery;
 }
 /**
  * How a session's process ended.
@@ -170,6 +192,19 @@ export interface SessionSnapshot {
         /** Exact harness-native approval/permission mode used by this runner. */
         nativeMode: string;
     };
+    /**
+     * 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
+     * evidence is not evidence of inactivity.
+     */
+    activity?: SessionActivity;
+}
+export interface SessionActivity {
+    /** ACP tool calls currently reserved (lifecycle open or permission pending). */
+    activeToolCalls: number;
+    /** When the agent last sent ANY session update, replay excluded. */
+    lastUpdateAt?: string;
 }
 export type SessionEventKind = 'state' | 'agent_text' | 'thought' | 'tool_call' | 'tool_update' | 'permission' | 'monitor_delivery' | 'turn_stop' | 'error';
 /** What a settled permission request resolved to. */

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 } from './config.js';
+import { type ApprovalMode, type FilesystemMode, type ResolvedRole, type RoleConfig, type MonitorConfig, type SessionBackendId, type UnattendedMode, type RoomStartupGate } from './config.js';
 import { type OpsDeps } from './ops.js';
 import { type CreationDeps, type CreationProvenance } from './creation.js';
 import './harness/claude-code.js';
@@ -46,12 +46,14 @@ export interface SpawnOpts {
     creationActionId?: string;
     /** Set only by a live role supervisor after a role-scoped proxy request. */
     callerRole?: string;
+    /** Trusted Fleet-internal gate for a Cowork room member; not a CLI/config surface. */
+    roomStartupGate?: RoomStartupGate;
     /** Internal provenance labels for values filled by the caller's supervisor. */
     inheritedFromCaller?: string[];
     /**
      * Path to a file holding exactly the existing `isolation:` mapping — the same
      * schema fleet.yaml uses, not a second policy language. The ONE new operator
-     * input in this release (6.3).
+     * input in this release.
      */
     isolationFile?: string;
     overseeInterval?: string;

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, daemonIdentityInventoryProvisioner, 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,19 +223,13 @@ 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');
-    const optionProblems = adapter.validateOptions(resolvedRole.harness_options);
+    const optionProblems = adapter.validateOptions(resolvedRole.harness_options, resolvedRole);
     if (optionProblems.length)
         throw new Error(optionProblems.map(problem => `${problem.path}: ${problem.message}`).join('; '));
     return {
@@ -236,7 +241,7 @@ export function spawnDryRun(o) {
 }
 /**
  * Which settings came from the operator, from fleet defaults, or from a
- * built-in (6.6). Built while the options are still separable — once they are
+ * built-in. Built while the options are still separable — once they are
  * merged into a ResolvedRole the distinction is gone.
  *
  * `env`, `bio`, `persona` and `harness_options` are deliberately absent: the
@@ -278,13 +283,13 @@ export async function spawnPermanent(o, deps, creation = {}) {
         readIsolationFile(o.isolationFile); // fail before reserving
     if (o.missionFile)
         readMissionFile(o.missionFile); // fail before reserving
-    // Name AND identity reserved together, before anything is written or started
-    // (6.4). A loser of the race creates no config, no state, no service.
+    // 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');
     return withCreationTransaction({ role: o.name, identity: effectiveIdentity(o) }, async (tx) => {
         assertNameFree(o);
         const cfg = loadConfig(o.configPath);
-        // Establish the identity BEFORE the service is enabled (7.3), and record
+        // 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);
@@ -317,7 +322,7 @@ export async function spawnPermanent(o, deps, creation = {}) {
                 rmSync(stateDir, { recursive: true, force: true }); },
         });
         // Journal the service registration BEFORE it happens, and undo only the
-        // registrations this transaction actually created (6.2). `registered` is
+        // registrations this transaction actually created. `registered` is
         // filled by `up`'s onInstalled hook at the moment each registration is
         // made — not from its return value, which never arrives when `up` throws
         // after registering.
@@ -328,7 +333,7 @@ export async function spawnPermanent(o, deps, creation = {}) {
                 await deps.backend.uninstall(n); },
         });
         // Provenance is written BEFORE the role starts, so a role that fails to
-        // launch still records how it was asked for (6.6).
+        // launch still records how it was asked for.
         const provenance = buildProvenance({
             role: o.name, lifetime: 'permanent', fleetVersion: VERSION,
             settings: provenanceSettings(o, cfg.defaults),
@@ -378,8 +383,8 @@ export async function spawnTemp(o, binPath, launch = independentSupervisor, crea
     // Retire only supervisors whose recorded owner is definitively stopped. This
     // bounded pass keeps the active roster clean without deleting old evidence.
     await reclaimStaleTempState();
-    // Temporary roles go through the SAME reservation boundary as permanent ones
-    // (6.4): a temp agent competes for the same names.
+    // Temporary roles go through the same reservation boundary as permanent ones:
+    // a temp agent competes for the same names.
     creation.onStage?.('reserving');
     return withCreationTransaction({ role: o.name, identity: effectiveIdentity(o) }, async (tx) => {
         creation.onStage?.('checking_identity');
@@ -408,7 +413,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
@@ -423,18 +439,15 @@ async function spawnTempInner(o, binPath, launch, tx, guarantee, onStage) {
         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 (design §2).
+        // 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: resolveAuthProxy(cfg.defaults.auth_proxy, fromOpts.auth_proxy),
+        auth_proxy: tempAuthProxy,
         sourceFile: '(temp)',
+        roomStartupGate: o.roomStartupGate,
     };
-    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/dist/supervisor/launchd.d.ts

@@ -6,7 +6,7 @@ export declare const labelFor: (name: string) => string;
  * asked of it cannot drift apart. They are not the same question:
  *
  * - `liveness` asks "does this role's context still exist" — a loaded job counts,
- *   including one waiting between KeepAlive restarts (1.1);
+ *   including one waiting between KeepAlive restarts;
  * - `install` asks "did the job I just bootstrapped actually START" — for which a
  *   job that is loaded, not running, and has already exited once is a failure.
  *
@@ -44,7 +44,7 @@ export interface LaunchdJob {
  * - loaded and running, or waiting for a KeepAlive restart, or not running with
  *   nothing exited yet (it simply has not been spawned yet — the asynchrony
  *   RunAtLoad introduces) → NOT a failure;
- * - an unreadable probe → `unknown`, never a failure (1.1). launchd may be fine
+ * - an unreadable probe → `unknown`, never a failure. launchd may be fine
  *   and the tool merely unable to answer.
  */
 export declare function classifyStart(job: LaunchdJob): {

package/dist/supervisor/launchd.js

@@ -23,7 +23,7 @@ function plist(name, binPath) {
   <key>Label</key><string>${labelFor(name)}</string>
   <key>ProgramArguments</key>
   <array><string>${binPath}</string><string>_run</string><string>${name}</string></array>
-  <!-- The runner owns the child-session restart loop (3.2). launchd must only
+  <!-- The runner owns the child-session restart loop. launchd must only
        recover the runner PROCESS crashing: a bare KeepAlive would resume the
        uncounted relaunch loop and restart a deliberately held-down agent. -->
   <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
@@ -50,7 +50,7 @@ function plist(name, binPath) {
  * - loaded and running, or waiting for a KeepAlive restart, or not running with
  *   nothing exited yet (it simply has not been spawned yet — the asynchrony
  *   RunAtLoad introduces) → NOT a failure;
- * - an unreadable probe → `unknown`, never a failure (1.1). launchd may be fine
+ * - an unreadable probe → `unknown`, never a failure. launchd may be fine
  *   and the tool merely unable to answer.
  */
 export function classifyStart(job) {
@@ -105,7 +105,7 @@ export function makeLaunchdBackend(exec = realExec, uid = process.getuid?.() ??
             writeFileSync(plistPath(name), plist(name, binPath));
             await exec('launchctl', ['bootout', `${domain}/${labelFor(name)}`]); // best-effort refresh
             // Undo only what WE wrote. A plist that was already there belongs to
-            // whoever put it there, and rollback may never remove it (6.2).
+            // whoever put it there, and rollback may never remove it.
             const undo = async () => {
                 if (existed)
                     return;
@@ -117,7 +117,7 @@ export function makeLaunchdBackend(exec = realExec, uid = process.getuid?.() ??
                 // The plist is already on disk, carrying RunAtLoad. Throwing here means
                 // `install` never returns `{created: true}`, so the creation transaction
                 // records nothing and its rollback removes nothing — and a spawn that
-                // failed at registration leaves a launch artifact behind (6.2). Undo our
+                // failed at registration leaves a launch artifact behind. Undo our
                 // own partial write before throwing, and only when WE wrote it.
                 await undo();
                 throw new Error(`launchctl bootstrap ${labelFor(name)} failed: ${r.stderr.trim()}`);