omp-conductor 0.15.13 → 0.16.0

package/src/model-fallback.ts

@@ -26,6 +26,7 @@ import type { FailureClass, RunRecord } from "./types.ts";
 export const FAILOVER_CLASSES: readonly FailureClass[] = [
   "provider-transient",
   "provider-credit",
+  "provider-capacity",
 ];
 
 /** The default for a project's `modelFallbackThreshold` when it is absent or
@@ -44,7 +45,7 @@ export interface ProviderFailureFacts {
   /** How many terminal runs at the head of the chain failed as a provider. */
   streak: number;
   /** Those runs' classes, newest first — the set is either one class or a mix
-   *  of `provider-transient` and `provider-credit`. */
+   *  of `provider-transient`, `provider-credit` and `provider-capacity`. */
   classes: FailureClass[];
   /**
    * The model the most recent failure dispatched on, when its row recorded
@@ -97,7 +98,7 @@ export interface ModelChoice {
  * returned unchanged and `fallback` stays false — today's dispatch byte for
  * byte. Once the streak reaches the threshold the chain advances one slot per
  * extra failure, clamped to the last model: the chain is exhausted there, and
- * the existing escalation path (the provider-transient strike cap) settles it,
+ * the existing escalation path (the provider-class strike cap) settles it,
  * naming every model tried.
  */
 export function resolveDispatchModel(args: {

package/src/omp-settings.ts

@@ -0,0 +1,114 @@
+/**
+ * The fleet-owned omp settings overlay (#537).
+ *
+ * Workers inherit omp configuration from the daemon account's global
+ * `~/.omp/agent/config.yml` and nothing else. This module is the channel for
+ * saying "this project's workers run with *these* omp settings" without
+ * editing that fleet-wide file: a project's `ompSettings` map (an opaque
+ * settings tree the harness owns) is materialised to a YAML overlay *outside
+ * the worktree* — under the run's own session directory, alongside the
+ * transcript and the control socket — and threaded to the session through
+ * omp's own `Settings.init({ configFiles: [<path>] })` seam.
+ *
+ * Two properties make this channel distinct from the obvious alternative of
+ * writing `<worktree>/.omp/config.yml`:
+ *
+ *   - The overlay is fleet-owned, never a file in the git checkout, so the
+ *     diff a worker eventually ships is untouched and nothing needs an ignore
+ *     entry. The worktree ignore block's standing rule — an ignored new file
+ *     is invisible to salvage — is exactly why an in-tree staging was refused.
+ *   - It is rewritten from config on every dispatch, so a config edit takes
+ *     effect on the next attempt (and a resumed attempt reuses the kept
+ *     session directory with the *current* config, not the one as of first
+ *     provision).
+ *
+ * Conductor validates YAML shape only — omp owns the schema. An unknown key or
+ * a wrong-typed value is omp's to reject when it resolves the overlay, never
+ * conductor's to interpret.
+ */
+
+import { unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { stateDir } from "./config.ts";
+import type { ProjectConfig } from "./types.ts";
+
+/** The overlay filename inside a run's session directory. */
+export const OMP_SETTINGS_FILE = "omp-settings.yml";
+
+/**
+ * The effective overlay map for a project: the opaque `ompSettings` map plus
+ * the retry keys (`retry.modelFallback`, `retry.fallbackChains.default`)
+ * derived from `modelFallbacks` — #539's staging half, moved onto this general
+ * channel so there is one way to stage settings into a worker session, not one
+ * seam per feature.
+ *
+ * `ompSettings.retry` is the operator's explicit word: when it is already a
+ * mapping, the derived retry block is skipped entirely (the overlay then says
+ * what it says, and the dispatch-failover chain #286 reads is unchanged — only
+ * omp's *retry-time* model swap respects the explicit stanza). Otherwise the
+ * derived block is merged in, preserving #539's behaviour exactly.
+ *
+ * Returns `undefined` when nothing is staged — a project with neither an
+ * `ompSettings` map nor a model-fallback chain gets no overlay at all, so its
+ * dispatch is byte-for-byte today's.
+ */
+export function ompSettingsOverlay(
+  p: Pick<ProjectConfig, "ompSettings" | "modelFallbacks">,
+): Record<string, unknown> | undefined {
+  const map: Record<string, unknown> = { ...(p.ompSettings ?? {}) };
+  const chain = p.modelFallbacks;
+  const explicitRetry =
+    typeof map.retry === "object" && map.retry !== null && !Array.isArray(map.retry);
+  if (chain !== undefined && chain.length > 0 && !explicitRetry) {
+    map.retry = {
+      modelFallback: true,
+      fallbackChains: { default: [...chain] },
+    };
+  }
+  return Object.keys(map).length === 0 ? undefined : map;
+}
+
+/**
+ * The directory every run's session dir lives under — where the overlay is
+ * materialised at dispatch. `doctor` probes its writability to report whether
+ * the next dispatch's overlay can actually land.
+ */
+export function sessionRootDir(): string {
+  return join(stateDir(), "sessions");
+}
+
+/**
+ * Materialises a project's effective overlay to `<sessionDir>/omp-settings.yml`
+ * and returns its absolute path, or `undefined` when nothing is staged.
+ *
+ * When nothing is staged, any overlay a previous attempt wrote is removed, so
+ * a project that dropped its map leaves no stale file in a kept session dir —
+ * the resume path reuses that directory, and an orphaned overlay with nobody
+ * reading it would be the exact silent fake this channel exists to avoid.
+ *
+ * Re-runs every dispatch, so a kept worktree picks up a config change on the
+ * next attempt rather than at the next worktree creation. A non-staged
+ * project's dispatch degrades to the harness discovering settings exactly as
+ * it always has.
+ */
+export function materializeOmpSettings(
+  project: Pick<ProjectConfig, "ompSettings" | "modelFallbacks">,
+  sessionDir: string,
+): string | undefined {
+  const path = join(sessionDir, OMP_SETTINGS_FILE);
+  const overlay = ompSettingsOverlay(project);
+  if (overlay === undefined) {
+    try {
+      unlinkSync(path);
+    } catch {
+      // Nothing written — a fresh session dir, or the absent case on first
+      // dispatch. Either way there is no stale overlay to remove.
+    }
+    return undefined;
+  }
+  // 0600: the overlay can carry provider names and model selectors, and the
+  // session dir already holds the run's private channels.
+  writeFileSync(path, stringify(overlay), { mode: 0o600 });
+  return path;
+}

package/src/omp.ts

@@ -168,6 +168,17 @@ export async function createLocalSession(opts: {
   releaseGrants?: ResolvedGrants;
   /** Durable audit callback invoked only when that gate rejects a call. */
   onReleaseBlocked?: (shape: GateShape, context: ReleaseBlockContext) => void;
+  /**
+   * The fleet-owned omp settings overlay staged into this session's omp
+   * settings (#537): an absolute path to a YAML overlay the daemon materialised
+   * from the project's `ompSettings` map (plus the retry keys derived from
+   * `modelFallbacks`), passed to `Settings.init({ configFiles: [<path>] })` so
+   * it layers on top of the ordinary global/project discovery — never an
+   * isolated instance, which would drop providers and approvals out from under
+   * the worker. Absent, no settings are passed and the harness discovers
+   * exactly as it does today.
+   */
+  ompSettingsFile?: string;
   /**
    * The conductor verb socket this session's mutation tools call (#126).
    *
@@ -243,11 +254,31 @@ export async function createLocalSession(opts: {
     conductorVerbs(opts.verbSocketPath),
   ];
 
+  // The fleet-owned omp settings overlay (#537): when the daemon staged one,
+  // layer it into a Settings instance over the ordinary global/project
+  // discovery. `Settings.init({ cwd, configFiles })` keeps the daemon account's
+  // global config (providers, approvals, modelRoles) and any project
+  // `.omp/config.yml` intact — the overlay is deep-merged *after* them — and
+  // never `Settings.isolated()`, which would build from the overlay alone and
+  // drop everything out from under the worker. Absent a staged overlay, no
+  // settings are passed and the harness discovers exactly as it does today.
+  let overlaySettings: unknown = undefined;
+  if (opts.ompSettingsFile !== undefined) {
+    const Settings = Reflect.get(namespace, "Settings");
+    if (typeof Settings === "function" && typeof Settings.init === "function") {
+      overlaySettings = await Settings.init({
+        cwd: opts.cwd,
+        configFiles: [opts.ompSettingsFile],
+      });
+    }
+  }
+
   const created = await mod.createAgentSession({
     cwd: opts.cwd,
     // A raw pattern rather than a resolved Model: the harness resolves it
     // after extensions load, so we never have to import its model registry.
     ...(opts.model === undefined ? {} : { modelPattern: opts.model }),
+    ...(overlaySettings === undefined ? {} : { settings: overlaySettings }),
     sessionManager,
     // A private registry per session, never the process-global default: that
     // one admits only one "Main" identity per generation, so a second session
@@ -424,6 +455,13 @@ export interface CreateSessionOptions {
   role: SessionRole;
   releaseGrants?: ResolvedGrants;
   onReleaseBlocked?: (shape: GateShape, context: ReleaseBlockContext) => void;
+  /**
+   * Absolute path to the fleet-owned omp settings overlay (#537), forwarded to
+   * the child through the host spec so the far side's `createLocalSession`
+   * loads it via `Settings.init({ configFiles: [<path>] })`. Absent, nothing
+   * is staged and the session discovers settings as it does today.
+   */
+  ompSettingsFile?: string;
 
   /**
    * Where the control socket is bound. The daemon puts it beside the run's own
@@ -562,6 +600,7 @@ export async function createSession(opts: CreateSessionOptions): Promise<AgentSe
     ...(opts.releaseGrants === undefined ? {} : { releaseGrants: opts.releaseGrants }),
     ...(opts.verbSocketPath === undefined ? {} : { verbSocketPath: opts.verbSocketPath }),
     ...(opts.readOnly === undefined ? {} : { readOnly: opts.readOnly }),
+    ...(opts.ompSettingsFile === undefined ? {} : { ompSettingsFile: opts.ompSettingsFile }),
   };
 
   const log = opts.onChildLog ?? ((line: string) => process.stderr.write(`${line}\n`));

package/src/orchestrator-tick.ts

@@ -519,7 +519,13 @@ export function queueDigestLine(
   if (summary.routed >= groomBelow) return undefined;
   let line = `Queue: running low — ${summary.routed} routable candidate(s), below the grooming trigger of ${groomBelow}.`;
   if (summary.admitted === 0 && summary.holds.length > 0) {
-    line += ` All held: ${summary.holds.map((h) => `${h.reason} ${h.count}`).join(", ")}.`;
+    const held = summary.holds
+      .map((h) => {
+        const first = h.details?.[0];
+        return `${h.reason} ${h.count}${first === undefined ? "" : ` (${first})`}`;
+      })
+      .join(", ");
+    line += ` All held: ${held}.`;
   }
   return line;
 }

package/src/reports.ts

@@ -37,7 +37,14 @@
  */
 
 import { availabilityDisposition, interruptDisposition } from "./availability.ts";
-import { readTelegramToken, resolveProjectTopicId, sendTelegram, TelegramSendError } from "./escalate.ts";
+import {
+  readTelegramToken,
+  resolveProjectTopicId,
+  sendTelegram,
+  telegramTextParts,
+  TelegramSendError,
+} from "./escalate.ts";
+import { createHash } from "node:crypto";
 import { localDayKey } from "./digest-schedule.ts";
 import {
   DIGEST_BACKLOG_LIMIT,
@@ -86,11 +93,68 @@ const NO_ISSUE = 0;
 const ERROR_SAMPLE = 90;
 
 /**
- * One delivery attempt's transport. Injected so the delivery contract — claim,
- * send, record, retry — is testable without a live bot, which is the same split
- * `confineToolCall` and `verifyPr` use: the decision is separable from the I/O.
- * Resolves with Telegram's own message id when it returns one, throws on any
- * known failure.
+ * The within-run harness reliability a settlement now names where a human
+ * reads it (#584). The row always carries the resolved model/provider and the
+ * counts (written at settlement straight off the worker result); this is only
+ * the *wording* — the sentence a settlement report and a tick digest tell an
+ * operator who would otherwise have to read a transcript to learn that the
+ * run finished on a fallback after a mid-run swap, or rode out a throttled
+ * provider on retries and compaction.
+ *
+ * Deliberately empty for a clean run: a run that never swapped, retried or
+ * compacted changes neither the settlement report nor the digest, so the
+ * "additive" claim is the observable one — byte-for-byte today's output on a
+ * quiet fleet. The resolved model is still recorded on the row every time (#584's
+ * second fake), but a clean run's narrative has nothing to add.
+ */
+export interface ReliabilitySettlement {
+  resolvedModel?: string;
+  resolvedProvider?: string;
+  retryFallbacks: { from: string; to: string }[];
+  retryFallbackSucceeded: number;
+  modelRecoveries: number;
+  autoRetryCount: number;
+  autoCompactionCount: number;
+}
+
+/**
+ * The human sentence for the above reliability surface, or undefined when there
+ * is nothing worth saying (a clean run). One line so it drops into both the
+ * settlement report and a material event's summary unchanged.
+ */
+export function reliabilitySettlementLine(
+  f: ReliabilitySettlement,
+): string | undefined {
+  const { resolvedModel, resolvedProvider } = f;
+  if (f.retryFallbacks.length === 0 && f.retryFallbackSucceeded === 0 && f.modelRecoveries === 0 && f.autoRetryCount === 0 && f.autoCompactionCount === 0) {
+    return undefined;
+  }
+  const activity = [
+    f.retryFallbacks.length > 0
+      ? `${f.retryFallbacks.length} within-run model swap${f.retryFallbacks.length === 1 ? "" : "s"}`
+      : undefined,
+    f.retryFallbackSucceeded > 0 ? `${f.retryFallbackSucceeded} recovered` : undefined,
+    f.modelRecoveries > 0 ? `${f.modelRecoveries} model recovery` : undefined,
+    f.autoRetryCount > 0 ? `${f.autoRetryCount} provider retry` : undefined,
+    f.autoCompactionCount > 0 ? `${f.autoCompactionCount} compaction` : undefined,
+  ].filter((part): part is string => part !== undefined);
+  const finished =
+    resolvedModel === undefined
+      ? "finished on the fallback"
+      : `finished on ${resolvedModel}${resolvedProvider === undefined ? "" : ` (${resolvedProvider})`}`;
+  return `Reliability: ${activity.join(", ")}; ${finished}.`;
+}
+
+/**
+ * One delivery attempt's transport for a *single message*. Injected so the
+ * delivery contract — claim, split, send, record progress, retry — is testable
+ * without a live bot, which is the same split `confineToolCall` and `verifyPr`
+ * use: the decision is separable from the I/O. The outbox splits a long report
+ * into labelled parts itself and drives one call per part (so partial progress
+ * can be persisted and resumed, #566); a text passed here is always under the
+ * wire limit. Resolves with Telegram's own message id when it returns one,
+ * throws on any known failure — {@link TelegramSendError} carries the
+ * definitive/unknown verdict the retry's honesty hangs on.
  */
 export type ReportSend = (text: string) => Promise<number | undefined>;
 
@@ -291,7 +355,14 @@ export function telegramReportSend(p: ProjectConfig): ReportSend {
         "definitive",
       );
     }
-    return await sendTelegram(token, chatId, text, { topicId: resolveProjectTopicId(p) });
+    // `sendTelegram` splits internally and resolves with every part's id. A
+    // caller on this seam always passes one message under the wire limit, so a
+    // single-element array comes back; `[0]` is that one id. A text over the
+    // limit would still be delivered whole (never truncated) — the seam would
+    // simply under-report the extra ids, which is why the split lives at the
+    // caller, not here.
+    const ids = await sendTelegram(token, chatId, text, { topicId: resolveProjectTopicId(p) });
+    return ids[0];
   };
 }
 
@@ -345,7 +416,13 @@ export async function deliverOperatorMessage(
     });
     return { kind: "held", category, noticeId: deps.noticeId, reason: disposition };
   }
-  await (deps.send ?? telegramReportSend(project))(text);
+  const send = deps.send ?? telegramReportSend(project);
+  // A long operator message is split and driven part-by-part through the same
+  // seam the outbox uses, so a custom transport sees the same per-part calls
+  // and the default one never truncates (#566).
+  for (const part of telegramTextParts(text)) {
+    await send(part);
+  }
   return { kind: "sent", category };
 }
 
@@ -596,9 +673,38 @@ export function createReportOutbox(deps: ReportOutboxDeps): ReportOutbox {
       return;
     }
 
-    let messageId: number | undefined;
+    const text = formatReportMessage(claimed, project.name);
+    const parts = telegramTextParts(text);
+    // Fingerprint of the exact text the split below is computed from. The
+    // per-part watermark on the row is only meaningful while this is unchanged:
+    // the resume point is a count into a specific split, so any drift in the
+    // text invalidates it (#566).
+    const messageHash = createHash("sha256").update(text).digest("hex");
+    // Resume at the first part this attempt has not yet confirmed. A count is
+    // only a valid resume point while the text — and therefore the split — is
+    // byte-identical to the attempt that wrote the watermark. Any change,
+    // notably the possible-repeat banner an unknown outcome adds to an
+    // ambiguous report, reshapes the parts, so the watermark is deliberately
+    // not carried across it and the whole report is re-sent amber-flagged —
+    // the same at-least-once semantics as the single-message path (#566).
+    const resumeAt = claimed.sentPartsHash === messageHash ? (claimed.sentParts ?? 0) : 0;
+    const start = Math.min(resumeAt, parts.length);
+
+    const messageIds: number[] = [];
     try {
-      messageId = await send(formatReportMessage(claimed, project.name));
+      // Strictly in order, one `sendMessage` at a time: parts never interleave
+      // with each other or with a message sent concurrently to the same chat.
+      for (let i = start; i < parts.length; i += 1) {
+        const id = await send(parts[i]!);
+        if (id !== undefined) messageIds.push(id);
+        // Persist progress before the next part ships. Only a multi-part send
+        // has a crossing point to protect: a crash or a definitive failure can
+        // then only ever re-send the part that was in flight, never the
+        // confirmed prefix. Guarded by attempt id like every other transition.
+        if (parts.length > 1) {
+          store.markReportPartsSent(claimed.id, attemptId, i + 1, messageHash, now());
+        }
+      }
     } catch (err) {
       const at = now();
       const error = err instanceof Error ? err.message : String(err);
@@ -641,15 +747,21 @@ export function createReportOutbox(deps: ReportOutboxDeps): ReportOutbox {
       pass.requeued.push(claimed.id);
       log(
         `report ${claimed.id} attempt ${claimed.attempts}/${REPORT_MAX_ATTEMPTS} was rejected, ` +
+          `${start + messageIds.length}/${parts.length} parts accepted, ` +
           `retrying in ${Math.round(delay / 1_000)}s: ${error}`,
       );
       return;
     }
 
-    store.markReportDelivered(claimed.id, attemptId, messageId, now());
+    store.markReportDelivered(claimed.id, attemptId, messageIds, now());
     pass.delivered.push(claimed.id);
     log(
-      `report ${claimed.id} delivered${messageId === undefined ? "" : ` as telegram message ${messageId}`}` +
+      `report ${claimed.id} delivered` +
+        (parts.length === 1
+          ? messageIds[0] === undefined
+            ? ""
+            : ` as telegram message ${messageIds[0]}`
+          : ` as ${parts.length} telegram messages (${messageIds.join(", ")})`) +
         `${claimed.ambiguous ? " (marked as a possible repeat)" : ""}`,
     );
   };

package/src/session-host.ts

@@ -50,6 +50,11 @@ export interface SessionHostSpec {
   verbSocketPath?: string;
   /** Deny every tool but reading and searching (#307) — the setup probes. */
   readOnly?: boolean;
+  /** The fleet-owned omp settings overlay (#537): absolute path to the YAML
+   *  overlay the daemon materialised from the project's `ompSettings` map.
+   *  Carried as a plain scalar like the other fields; absent, nothing is staged
+   *  on the far side either. */
+  ompSettingsFile?: string;
 }
 
 /** Parent → child. */
@@ -186,6 +191,7 @@ export async function runSessionHost(
       ...(spec.releaseGrants === undefined ? {} : { releaseGrants: spec.releaseGrants }),
       ...(spec.verbSocketPath === undefined ? {} : { verbSocketPath: spec.verbSocketPath }),
       ...(spec.readOnly === undefined ? {} : { readOnly: spec.readOnly }),
+      ...(spec.ompSettingsFile === undefined ? {} : { ompSettingsFile: spec.ompSettingsFile }),
       // The release audit lives in the daemon's state directory, which this
       // process may not be able to write and must not be trusted to. It
       // becomes a message; the parent performs the durable write.

package/src/setup-wizard.ts

@@ -71,6 +71,7 @@ import {
   detectTelegram,
   formatGates,
   orchestratorBriefPath,
+  parseOmpSettingsYaml,
   planAgainstLabels,
   planLabels,
   summariseAmend,
@@ -1204,6 +1205,37 @@ const askWorkerModel: AreaAsker = async (ui, a) => {
   return next;
 };
 
+/** The free-form omp settings overlay (#537): one YAML answer, omp's own
+ *  vocabulary rather than a list this package can offer. The seed is the
+ *  current map rendered as JSON — a YAML 1.2 subset — so a re-run that Enters
+ *  re-affirms it on one line; a blank answer clears the overlay; anything that
+ *  is not a YAML mapping re-asks, because an answer the dispatcher would
+ *  silently drop is exactly the input this wizard exists to catch. */
+const askOmpSettings: AreaAsker = async (ui, a) => {
+  const next: SetupAnswers = { ...a };
+  const seed = a.ompSettings === undefined ? "" : JSON.stringify(a.ompSettings);
+  const answered = await askValid(
+    ui,
+    "Omp settings overlay for workers (YAML, blank = none — omp's schema, not conductor's)",
+    seed,
+    (value) => {
+      if (value.trim().length === 0) return undefined;
+      const parsed = parseOmpSettingsYaml(value);
+      return parsed.ok ? undefined : parsed.problem;
+    },
+  );
+  if (answered.trim().length === 0) {
+    delete next.ompSettings;
+    return next;
+  }
+  const parsed = parseOmpSettingsYaml(answered);
+  // askValid already proved the shape on this exact string; a parse failure
+  // here is an internal invariant, never a silently dropped overlay.
+  if (!parsed.ok) throw new Error(`unreachable: askValid accepted unparseable omp settings: ${parsed.problem}`);
+  next.ompSettings = parsed.value;
+  return next;
+};
+
 /** The three ownership questions, then the mechanical gate one shape at a time:
  *  together they are what decides what an unattended fleet may do unasked. */
 const askAuthorityArea: AreaAsker = async (ui, a, _probes, discovered) => {
@@ -1492,6 +1524,7 @@ const AREA_ASKERS: { readonly [K in AmendAreaId]: AreaAsker } = {
   // The two per-worker knobs the full interview separates with the authority
   // grants; an amend has no reason to put anything between them.
   caps: async (ui, a, probes) => await askWorkerModel(ui, await askCaps(ui, a, probes), probes),
+  "omp-settings": askOmpSettings,
   "code-graph": askGraph,
   authority: askAuthorityArea,
   policy: askPolicy,
@@ -1528,6 +1561,9 @@ const INTERVIEW_AREAS: readonly { label: string; asker: AreaAsker }[] = [
   { label: "authority & release grants", asker: askAuthorityArea },
   { label: "merge & release preconditions", asker: askPolicy },
   { label: "worker model", asker: askWorkerModel },
+  // The omp settings overlay rides next to the worker model: both are
+  // per-worker runtime knobs, and neither is a ceiling the caps block owns.
+  { label: "omp settings overlay", asker: askOmpSettings },
   { label: "escalation & triage", asker: askEscalation },
   { label: "reporting", asker: askReporting },
   { label: "orchestrator brief", asker: askBrief },

package/src/setup.ts

@@ -23,6 +23,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { parse as parseYaml } from "yaml";
 import {
   COMPOSE_BANNER,
   ORCHESTRATOR_BRIEF_NAME,
@@ -46,6 +47,7 @@ import {
   stateDir,
 } from "./config.ts";
 import { graphProjectPath, graphRepos } from "./graph.ts";
+import { ompSettingsOverlay } from "./omp-settings.ts";
 import {
   CONFIG_VERSION,
   DEFAULT_AUTHORITY,
@@ -163,6 +165,15 @@ export interface SetupAnswers {
    */
   modelFallbacks?: string[];
   modelFallbackThreshold?: number;
+  /**
+   * The project's omp settings overlay (#537): an opaque map layered into
+   * every worker session via the fleet-owned settings channel. The wizard asks
+   * for it as one free-form YAML answer (the only prompt this map gets — the
+   * keys inside it are omp's vocabulary, not a list conductor can offer); it
+   * also survives an amend of any other area unchanged, like
+   * {@link modelFallbacks}.
+   */
+  ompSettings?: Record<string, unknown>;
   telegramChatId?: string;
   /** Forum topic for tier-2 Telegram pages; absent keeps flat-chat 0.13 behaviour. */
   telegramTopicId?: number;
@@ -855,6 +866,9 @@ export function buildProject(a: SetupAnswers): ProjectConfig {
     // would pin every run of the project onto a dead provider again (#286).
     ...(a.modelFallbacks === undefined ? {} : { modelFallbacks: [...a.modelFallbacks] }),
     ...(a.modelFallbackThreshold === undefined ? {} : { modelFallbackThreshold: a.modelFallbackThreshold }),
+    // The omp settings overlay is an opaque map the wizard collects as free-form
+    // YAML; an unrelated amend must not delete it (#537).
+    ...(a.ompSettings === undefined ? {} : { ompSettings: a.ompSettings }),
     escalation,
     authority: { ...a.authority },
     // Written out in full, never as the legacy string: the file then says which
@@ -1061,6 +1075,7 @@ export function answersFromProject(p: ProjectConfig): SetupAnswers {
   if (p.groomBelow !== undefined) answers.groomBelow = p.groomBelow;
   if (p.modelFallbacks !== undefined) answers.modelFallbacks = [...p.modelFallbacks];
   if (p.modelFallbackThreshold !== undefined) answers.modelFallbackThreshold = p.modelFallbackThreshold;
+  if (p.ompSettings !== undefined) answers.ompSettings = { ...p.ompSettings };
   if (p.escalation.telegramChatId !== undefined) answers.telegramChatId = p.escalation.telegramChatId;
   if (p.escalation.telegramTopicId !== undefined) answers.telegramTopicId = p.escalation.telegramTopicId;
   if (p.recoveryMerges !== undefined) {
@@ -1682,19 +1697,47 @@ export function formatGates(gates: readonly { cmd: string; cwd: string }[]): str
   return gates.map((g) => (g.cwd === "." ? g.cmd : `${g.cmd} @ ${g.cwd}`)).join(", ");
 }
 
+/**
+ * Parses the wizard's free-form YAML answer for a project's omp settings
+ * overlay (#537) and validates YAML shape only — the same boundary the config
+ * loader enforces. A mapping at the document root is the whole contract:
+ * everything inside it is omp's schema to own, so an unknown key or a
+ * wrong-typed value is omp's to reject, never this module's to understand
+ * (non-string keys are coerced by the YAML parser exactly as omp's own loader
+ * coerces them, so a `true: x` mapping stays YAML-valid on both sides). Blank
+ * input is a valid "no overlay" answer.
+ */
+export function parseOmpSettingsYaml(
+  text: string,
+): { ok: true; value: Record<string, unknown> } | { ok: false; problem: string } {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return { ok: true, value: {} };
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(trimmed);
+  } catch (err) {
+    return { ok: false, problem: `"${text}" is not valid YAML: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { ok: false, problem: "the omp settings overlay must be a YAML mapping at the root, e.g. `modelRoles: { worker: \"@slow\" }`" };
+  }
+  return { ok: true, value: parsed as Record<string, unknown> };
+}
+
 /**
  * The wizard's questions, grouped as the areas a re-run can amend one of, in the
  * order the full interview asks them.
  *
  * Data rather than a switch so the menu, the CLI's positional area vocabulary,
  * ./setup-wizard.ts's `AREA_ASKERS` table and the amend summary all enumerate the
- * same nine areas: an added area fails to compile until it has a name, a current
+ * same ten areas: an added area fails to compile until it has a name, a current
  * value and a set of questions.
  */
 export const AMEND_AREA_IDS = [
   "tracker",
   "gates",
   "caps",
+  "omp-settings",
   "code-graph",
   "authority",
   "policy",
@@ -1765,6 +1808,20 @@ export const AMEND_AREAS: {
       );
     },
   },
+  "omp-settings": {
+    // The free-form omp settings overlay (#537), the sibling per-worker knob to
+    // the model: one area no menu offers is a setting only a full re-interview
+    // can reach, so this one has its own row like the caps.
+    name: "omp settings overlay",
+    asks: "the free-form YAML map layered into every worker session's omp settings — omp's schema, not conductor's",
+    // The *effective* overlay — `ompSettings` plus the retry keys derived from
+    // `modelFallbacks` — so the menu says what a worker would actually load,
+    // matching `doctor` and the dispatcher rather than echoing raw config.
+    describe: (p) => {
+      const overlay = ompSettingsOverlay(p);
+      return overlay === undefined ? "no overlay — workers inherit global settings" : JSON.stringify(overlay);
+    },
+  },
   "code-graph": {
     name: "code graph",
     asks: "whether workers query a code-graph index, and the root its one-clone-per-repo lives under",