@ours.network/fleet 0.17.8 → 0.17.10

package/dist/harness/types.d.ts

@@ -1,3 +1,4 @@
+import type { McpServer } from '@agentclientprotocol/sdk';
 import type { CommonPermissions, FleetPermissionMode, ResolvedRole } from '../config.js';
 export interface PrereqCheck {
     name: string;
@@ -21,7 +22,32 @@ export interface SessionPrep {
     env: Record<string, string>;
     /** Optional launcher selected after runtime prerequisite probing. */
     command?: string;
+    /**
+     * The settings overlay prepareSession wrote, if it wrote one.
+     *
+     * The tmux launch delivers this as `--settings <path>` in `argv`; an ACP agent
+     * takes no flags, so it needs the PATH rather than the flag. Recorded here so
+     * the two deliveries read one value instead of each re-deriving the filename.
+     */
+    settingsOverlay?: string;
+    /**
+     * The MCP config file prepareSession wrote for `harness_options.mcp_servers`,
+     * if the role declared any. Same reason as `settingsOverlay`: the tmux launch
+     * passes the file, the ACP launch has to send the servers themselves.
+     */
+    mcpConfigFile?: string;
 }
+/**
+ * One MCP server as ACP's `session/new` declares it.
+ *
+ * ⚠ THE PROTOCOL'S OWN TYPE, DELIBERATELY NOT A LOCAL RESTATEMENT. `mcpServers`
+ * goes onto the wire unchanged, so a hand-written near-copy would compile while
+ * being subtly wrong — `env` and `headers` are REQUIRED arrays, and the stdio
+ * variant is the one with no `type` field at all. Aliasing it also keeps
+ * `session/new`'s response type inferable, which a structural stand-in silently
+ * broke (every field of the result degraded to `unknown`).
+ */
+export type AcpMcpServer = McpServer;
 export interface Launch {
     argv: string[];
     env: Record<string, string>;
@@ -96,7 +122,13 @@ export interface HarnessAdapter {
     id: string;
     supportsResume: boolean;
     checkPrereqs(): Promise<PrereqReport>;
-    validateOptions(opts: unknown): ValidationError[];
+    /**
+     * `role` is the SESSION-AWARE half: some harness options can only be honoured
+     * on some session types, and an option that is silently dropped is worse than
+     * one that is refused. Optional so an adapter that has nothing session-specific
+     * to say keeps its one-argument implementation.
+     */
+    validateOptions(opts: unknown, role?: ResolvedRole): ValidationError[];
     prepareSession(role: ResolvedRole, dirs: RoleDirs): Promise<SessionPrep>;
     buildLaunch(role: ResolvedRole, mode: 'fresh' | 'resume', s: SessionState, prep: SessionPrep): Launch;
     buildAcpLaunch?(role: ResolvedRole, prep: SessionPrep): AcpLaunch;
@@ -106,6 +138,23 @@ export interface HarnessAdapter {
      * agent's default. Omit for a harness whose ACP agent has no modes.
      */
     acpPermissionModeId?(role: ResolvedRole): string | undefined;
+    /**
+     * The MCP servers this role declares, for the `mcpServers` array of ACP's
+     * `session/new` / `resume` / `load`. Empty (or omitted) leaves the agent's own
+     * configuration alone, which is what fleet has always sent.
+     */
+    acpMcpServers?(role: ResolvedRole): AcpMcpServer[];
+    /**
+     * Agent-specific `_meta` for `session/new` — how a capability the CLI takes as
+     * a flag reaches an ACP agent that accepts no flags.
+     *
+     * ⚠ THIS IS A PER-AGENT VOCABULARY, NOT PROTOCOL. `_meta` is free-form in ACP,
+     * so what an adapter puts here is only honoured by the agent it was written
+     * for. An adapter must therefore return nothing for an ACP command it did not
+     * choose, and the options that depend on it must be refused at validation for
+     * such a role rather than sent and silently ignored.
+     */
+    acpSessionMeta?(role: ResolvedRole, prep: SessionPrep): Record<string, unknown> | undefined;
     /** Effective portable policy and harness-native approval mode after native overrides win. */
     effectivePermissionMode?(role: ResolvedRole): {
         fleetMode: FleetPermissionMode;

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/ops.js

@@ -16,7 +16,7 @@ import { realExec } from './exec.js';
 /** Materialize a role's state dir from config: briefing + markers. Returns the dir. */
 export function applyRole(role, opts = {}) {
     const adapter = getAdapter(role.harness);
-    const errs = adapter.validateOptions(role.harness_options);
+    const errs = adapter.validateOptions(role.harness_options, role);
     if (errs.length)
         throw new Error(`role '${role.name}': ` + errs.map(e => `${e.path}: ${e.message}`).join('; '));
     const dir = agentDir(role.name, opts.temp === true);

package/dist/owner-channel/channel.d.ts

@@ -238,6 +238,16 @@ export declare class OwnerChannel implements OwnerChannelHandle {
     private warnOwnerOfUnauthorizedSender;
     private effectiveOwners;
     private authorizationIntegrity;
+    /**
+     * Report what the session actually did with the prompt, not what the config
+     * asked for. `interrupt: true` used to be reported as "your request
+     * interrupted the previous task" unconditionally; the session now answers
+     * whether anything was cancelled, whether the request is queued behind
+     * earlier prompts, or whether it is held until the current task reaches a
+     * safe stopping point. Backends that report no delivery state keep the old
+     * queuedBehind-based wording.
+     */
+    private acceptanceNotice;
     private complete;
     private commentsState;
     /** Model-authored commentary only; raw protocol/tool data never reaches here. */

package/dist/owner-channel/channel.js

@@ -715,11 +715,7 @@ export class OwnerChannel {
                 origin: { kind: 'owner', requestId,
                     ...(group.caption ? { displayText: String(group.caption.text ?? '') } : {}) },
             });
-            const accepted = this.options.config.interrupt
-                ? ownerNotices.receivedInterrupting()
-                : queued.queuedBehind > 0
-                    ? ownerNotices.receivedQueued(queued.queuedBehind)
-                    : ownerNotices.receivedStarted();
+            const accepted = this.acceptanceNotice(queued);
             handledWireIds.forEach(wire => this.inFlight.add(wire));
             const receipt = this.send(sender.id, accepted, originWireId).then(() => undefined).catch(error => {
                 this.logError(`attachment request ${requestId.slice(0, 12)} acceptance notice failed`, error);
@@ -860,14 +856,7 @@ export class OwnerChannel {
             this.state.remember(wireId);
             return true;
         }
-        // Interrupting the live turn does not remove prompts which were already
-        // accepted into the ACP queue. Never claim this request is running while
-        // the session itself says earlier work remains ahead of it.
-        const accepted = queued.queuedBehind > 0
-            ? ownerNotices.receivedQueued(queued.queuedBehind)
-            : this.options.config.interrupt
-                ? ownerNotices.receivedInterrupting()
-                : ownerNotices.receivedStarted();
+        const accepted = this.acceptanceNotice(queued);
         this.inFlight.add(wireId);
         const receipt = this.send(sender.id, accepted, wireId).then(() => undefined).catch(error => {
             this.logError(`request ${requestId.slice(0, 12)} acceptance notice failed`, error);
@@ -1253,6 +1242,32 @@ export class OwnerChannel {
     authorizationIntegrity() {
         return this.options.config.agent ? { ok: true } : this.authorizations.integrity();
     }
+    /**
+     * Report what the session actually did with the prompt, not what the config
+     * asked for. `interrupt: true` used to be reported as "your request
+     * interrupted the previous task" unconditionally; the session now answers
+     * whether anything was cancelled, whether the request is queued behind
+     * earlier prompts, or whether it is held until the current task reaches a
+     * safe stopping point. Backends that report no delivery state keep the old
+     * queuedBehind-based wording.
+     */
+    acceptanceNotice(queued) {
+        switch (queued.delivery) {
+            case 'interrupted': return ownerNotices.receivedInterrupting();
+            case 'deferred': return ownerNotices.receivedDeferred();
+            case 'queued': return ownerNotices.receivedQueued(Math.max(1, queued.queuedBehind));
+            case 'started': return ownerNotices.receivedStarted();
+            default:
+                // Interrupting the live turn does not remove prompts which were already
+                // accepted into the ACP queue. Never claim this request is running while
+                // the session itself says earlier work remains ahead of it.
+                return queued.queuedBehind > 0
+                    ? ownerNotices.receivedQueued(queued.queuedBehind)
+                    : this.options.config.interrupt
+                        ? ownerNotices.receivedInterrupting()
+                        : ownerNotices.receivedStarted();
+        }
+    }
     async complete(active, outbox, queued, activityCursor) {
         const progressMs = this.options.config.progress_interval_ms;
         let lastSeq = activityCursor;

package/dist/owner-channel/notices.d.ts

@@ -22,6 +22,13 @@ export declare const ownerNotices: {
     receivedStarted: () => string;
     receivedQueued: (queuedBehind: number) => string;
     receivedInterrupting: () => string;
+    /**
+     * The honest answer when the agent is mid-task and pre-empting it would have
+     * corrupted the conversation. Says "not started yet" rather than borrowing
+     * `receivedInterrupting`'s claim that something was cancelled for this
+     * request.
+     */
+    receivedDeferred: () => string;
     status: (role: string, snapshot: SessionSnapshot) => string;
     interrupted: (role: string) => string;
     /** The turn IS cancelled — say how, without implying the owner must retry. */

package/dist/owner-channel/notices.js

@@ -26,6 +26,15 @@ export const ownerNotices = {
     receivedInterrupting: () => "ℹ️ Message received. The agent's previous task was interrupted to prioritize "
         + 'this request, and it is now working on a response. '
         + 'The response will arrive in this channel when ready.',
+    /**
+     * The honest answer when the agent is mid-task and pre-empting it would have
+     * corrupted the conversation. Says "not started yet" rather than borrowing
+     * `receivedInterrupting`'s claim that something was cancelled for this
+     * request.
+     */
+    receivedDeferred: () => 'ℹ️ Message received and held. The agent is in the middle of a task that '
+        + 'cannot be interrupted safely; this request starts as soon as that work '
+        + 'reaches a stopping point. The response will arrive in this channel when ready.',
     status: (role, snapshot) => `📊 ${role} status: ${snapshot.readiness}; session is ${snapshot.alive ? 'online' : 'offline'}.`,
     interrupted: (role) => `🛑 Interrupt sent to ${role}'s active turn.`,
     /** The turn IS cancelled — say how, without implying the owner must retry. */

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
@@ -61,6 +70,23 @@ export declare function readExitRecord(path: string): ExitRecord | null;
 export declare const RESTART_LEDGER_FILE = ".restart-ledger.json";
 /** Consecutive immediate failures tolerated before the agent is held down. */
 export declare const RESTART_FAIL_THRESHOLD = 5;
+/**
+ * How the previous supervisor process ended.
+ *
+ * `abrupt` is the case the ledger used to miss entirely: an OOM-kill or any
+ * other external signal takes the supervisor down before it can write anything,
+ * the service manager restarts the unit, and every durable indicator still
+ * describes the run that died. A health check reading them reported "no
+ * restarts" for a role that had died and come back.
+ */
+export interface TerminationRecord {
+    class: 'clean' | 'abrupt' | 'unknown';
+    detail: string;
+    /** When the SURVIVING process observed it, not when it happened. */
+    observedAt: string;
+    /** Start time of the run that ended, when it was recorded. */
+    runStartedAt?: string;
+}
 export interface RestartLedger {
     version: 1;
     consecutiveImmediateFailures: number;
@@ -72,7 +98,29 @@ export interface RestartLedger {
     updatedAt: string;
     /** When the circuit opened, for the held-down status line. */
     openedAt?: string;
+    /** How the previous supervisor process ended, including abnormal exits. */
+    lastTermination?: TerminationRecord;
+    /** Supervisor processes that died without closing their run marker. */
+    abruptTerminations?: number;
+    /** Start of the supervisor run that owns this state directory now. */
+    supervisorStartedAt?: string;
 }
+/**
+ * Carried across a supervisor process's life so its successor can tell an
+ * orderly exit from a kill. Present on disk == "a supervisor believed it was
+ * running"; the next start finding one that is not its own is proof the
+ * previous process died without getting to write anything.
+ */
+export declare const RUN_MARKER_FILE = ".supervisor-run.json";
+/**
+ * Claim this state directory for the current supervisor process and report how
+ * the previous one ended. Runs BEFORE the first attempt, which is the whole
+ * point: after an abrupt kill nothing else writes until an attempt finishes,
+ * and an attempt can take minutes.
+ */
+export declare function claimSupervisorRun(dir: string, startedAt: string, pid?: number): TerminationRecord;
+/** Orderly exit: the successor must not read this run as a kill. */
+export declare function releaseSupervisorRun(dir: string): void;
 /** Bounded exponential backoff for the nth consecutive immediate failure. */
 export declare function backoffFor(consecutiveFailures: number): number;
 /** Read a role's restart ledger; a missing or corrupt one starts clean. */