tickmarkr 1.84.0 → 1.86.0

package/dist/config/config.js

@@ -1,8 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { parse, stringify } from "yaml";
+import picomatch from "picomatch";
+import { Document, parse } from "yaml";
 import { z } from "zod";
+import { CITED_MODEL_WINDOWS } from "../adapters/model-windows.js";
 import { stateDirName } from "../graph/graph.js";
 import { SHAPES, TIERS } from "../graph/schema.js";
 const TierEnum = z.enum(TIERS, {
@@ -10,6 +12,8 @@ const TierEnum = z.enum(TIERS, {
 });
 export const TIER_RANK = { cheap: 0, mid: 1, frontier: 2 };
 export const DEFAULT_DIFF_CAP = 60_000;
+// This is deliberately only a rejection guard. T20's cited table, not this floor, supplies each claim.
+export const MODEL_WINDOW_PLAUSIBILITY_FLOOR = 1_024;
 // v1.51 T1: routing.mode — a preset COMPILED INTO FLOORS at config load. The router never sees the
 // mode; it receives resolved floors only (the structural defense against the quality-silently-loses
 // class — no fourth runtime authority, no new precedence key).
@@ -38,12 +42,36 @@ export const MapEntrySchema = z.object({
     prefer: z.array(z.string()).optional(),
     escalate: z.boolean().optional(),
 });
+const DeclaredVendorSchema = z.string().trim().min(1, "vendor must be nonempty");
+const ModelOverrideSchema = z
+    .object({
+    vendor: DeclaredVendorSchema.optional(),
+    channel: z.enum(["sub", "api"]).optional(),
+})
+    .refine((override) => override.vendor !== undefined || override.channel !== undefined, {
+    message: "a model override must declare vendor, channel, or both",
+});
 export const TierEntrySchema = z.object({
-    vendor: z.string(),
+    vendor: DeclaredVendorSchema.nullable(),
     channel: z.enum(["sub", "api"]),
     models: z.record(z.string(), TierEnum),
+    // T19: keep model values scalar for existing consumers. Optional sibling metadata resolves before
+    // parent metadata in channelsFromConfig; neither provider prefixes nor adapter ids manufacture it.
+    modelOverrides: z.record(z.string(), ModelOverrideSchema).optional(),
     // v1.47 T3: optional per-model context-window sizes (tokens). Absent block ⇒ no doctor column, no plan lint.
     windows: z.record(z.string(), z.number().int().positive()).optional(),
+}).superRefine((entry, ctx) => {
+    if (entry.vendor !== null)
+        return;
+    for (const model of Object.keys(entry.models)) {
+        if (entry.modelOverrides?.[model]?.vendor)
+            continue;
+        ctx.addIssue({
+            code: "custom",
+            path: ["modelOverrides", model, "vendor"],
+            message: "vendor: null requires every configured model to declare a nonempty vendor override",
+        });
+    }
 });
 // v1.10 FLEET-06: optional routing.allow/deny fleet preference; absent blocks ⇒ byte-identical routing/discovery.
 // deny wins on conflict; presence of allow (even {} / empty arrays) activates allowlist (fail-closed).
@@ -73,6 +101,143 @@ export const SubPricingSchema = z
     windowsPerMonthHigh: z.number().int().positive(),
 })
     .refine((s) => s.windowsPerMonthLow <= s.windowsPerMonthHigh, "windowsPerMonthLow must be ≤ windowsPerMonthHigh");
+// ── Review participation (R3 of OVERSEER-RULING-20260731-velocity; OBS-186) ────────────────────
+// Participation is keyed on PATHS — what a task DECLARES at compile time and what its diff ACTUALLY
+// touches at gate time — never on complexity. `complexityThreshold` capped participation at a number
+// the authoring law forbade tasks from reaching, so cross-vendor review was unreachable by
+// construction while `required: true` claimed the opposite. Paths cannot drift out from under the
+// gate that way: the same predicate decides both ends.
+export const REVIEW_POLICIES = ["full", "judge-only"];
+/**
+ * The leaf class: work a judge alone can carry because there is no behaviour to review. It is CLOSED
+ * and enumerated here — documentation pages, the changelog, the release runbook, and the version
+ * mirrors a release bump rewrites. Everything else, including tests and scripts, is full-review work.
+ */
+export const REVIEW_LEAF_GLOBS = [
+    "docs/**", "CHANGELOG.md", "RELEASING.md", "package.json", "package-lock.json",
+];
+/**
+ * Membership is a POSITIVE rule, not a blacklist. A blacklist of source extensions is a list of the
+ * formats someone thought of, and everything nobody thought of — `docs/widget.vue`, `docs/site.svelte`,
+ * `docs/Makefile`, `docs/package.json`, an extensionless script — falls into the leaf class and skips
+ * its review. That direction of failure is the whole defect OBS-186 names, so the rule is inverted:
+ * under `docs/` a path is leaf work only when its extension is a DOCUMENTATION format. An unknown
+ * format is behaviour until proven otherwise, which is the fail-closed direction.
+ */
+const REVIEW_DOC_EXT_RE = /\.(?:md|mdx|markdown|txt|rst|adoc|asciidoc)$/i;
+/**
+ * The version mirrors a release bump rewrites — and ONLY at the repo root: `docs/package.json` is a
+ * real manifest for something, not a mirror. Membership here is still a claim about paths, and a
+ * manifest diff that moves more than the version field leaves the class; the gate re-tests that
+ * against the actual diff content (src/gates/review.ts) because a path cannot say it by itself.
+ */
+export const REVIEW_VERSION_MIRRORS = new Set(["package.json", "package-lock.json"]);
+/** The changelog and the release runbook, at the repo root, by exact name. */
+const REVIEW_LEAF_FILES = new Set(["CHANGELOG.md", "RELEASING.md"]);
+/**
+ * Paths whose review may never be skipped (R3): the gate/run/driver/adapter surface — lifecycle,
+ * demux, and everything that reaches a shell. Shipped as the default so the compile lint that
+ * enforces them is live in a repo that never configures anything.
+ */
+export const DEFAULT_REVIEW_CRITICAL_PATHS = [
+    "src/gates/**", "src/run/**", "src/drivers/**", "src/adapters/**",
+];
+const GLOB_META_RE = /[*?[\]{}]/;
+const normPath = (p) => p.replace(/^\.\//, "").trim();
+/**
+ * True when `path` — an ACTUAL path a diff touched — is provably leaf-class work. Enumerated, closed,
+ * and positive: the two named root files, the two root version mirrors, and documentation formats
+ * under `docs/`. Everything else, including a `.vue`/`.svelte`/`Makefile`/`package.json` parked under
+ * `docs/`, is behaviour and draws a full review.
+ */
+export function isReviewLeafPath(path) {
+    const p = normPath(path);
+    if (!p.length)
+        return false;
+    if (REVIEW_LEAF_FILES.has(p) || REVIEW_VERSION_MIRRORS.has(p))
+        return true;
+    return p.startsWith("docs/") && REVIEW_DOC_EXT_RE.test(p);
+}
+/**
+ * True when a DECLARED pattern may claim leaf work. A declaration is a claim about a directory, not
+ * a file: `docs/**` is how a documentation task declares itself and has to stay claimable, so a glob
+ * rooted at `docs/` reads leaf here while `docs/tool.ts` does not read leaf above. The claim is never
+ * the last word — reviewGate re-tests it against what the diff actually touched and promotes when the
+ * diff leaves the class. A glob rooted anywhere else can claim nothing.
+ */
+export function isReviewLeafDeclaration(pattern) {
+    const p = normPath(pattern);
+    if (!p.length)
+        return false;
+    return isReviewLeafPath(p) || (GLOB_META_RE.test(p) && p.startsWith("docs/"));
+}
+/** full beats judge-only. The join is monotone by construction: nothing here can LOWER a policy. */
+export function raiseReviewPolicy(...policies) {
+    return policies.includes("full") ? "full" : "judge-only";
+}
+/**
+ * The compiler's assignment, from the task's DECLARED files[]. judge-only only when EVERY declared
+ * path is provably leaf work — one non-leaf pattern (or an empty files[]) makes it full.
+ */
+export function declaredReviewPolicy(files) {
+    const declared = files.map(normPath).filter((f) => f.length > 0);
+    return declared.length > 0 && declared.every(isReviewLeafDeclaration) ? "judge-only" : "full";
+}
+/** The declared assignment after the operator's floor is applied — config may raise it, never lower it. */
+export function effectiveReviewPolicy(files, review) {
+    return raiseReviewPolicy(declaredReviewPolicy(files), review.policy);
+}
+/** The literal head of a pattern — everything before its first glob metacharacter. */
+const literalPrefix = (p) => {
+    const i = p.search(GLOB_META_RE);
+    return i < 0 ? p : p.slice(0, i);
+};
+/** The literal tail of a pattern — everything after its last glob metacharacter. */
+const literalSuffix = (p) => p.replace(/^.*[*?[\]{}]/s, "");
+const eitherWay = (a, b, rel) => rel(a, b) || rel(b, a);
+/**
+ * Do two GLOBS have a path in common? Exact glob-vs-glob intersection is undecidable in general, so
+ * this fails CLOSED: the pair is treated as intersecting unless their literal heads or their literal
+ * tails prove they cannot meet. `docs/**\/README.md` vs `docs/security/*.md` share the head `docs/`
+ * and the tail `.md` is a tail of `/README.md`, so `docs/security/README.md` is correctly flagged;
+ * `src/**\/*.ts` vs `src/**\/*.md` share a head but neither tail contains the other, so they are not.
+ */
+const globsMayIntersect = (a, b) => eitherWay(literalPrefix(a), literalPrefix(b), (x, y) => x.startsWith(y))
+    && eitherWay(literalSuffix(a), literalSuffix(b), (x, y) => x.endsWith(y));
+/**
+ * Declared patterns that intersect a critical path. Directional containment is the certain half — a
+ * critical `src/gates/**` contains a declared `src/gates/review.ts`, and a declared `docs/**` contains
+ * a critical `docs/security/**`. It is NOT intersection: two globs can overlap without either matching
+ * the other as a literal string, which is how a judge-only task declaring `docs/**\/README.md` slipped
+ * past a critical `docs/security/*.md`. When BOTH sides are globs the conservative overlap test above
+ * decides, and it decides toward flagging — an over-flagged task is narrowed by its author, an
+ * under-flagged one skips the only gate that exists for it.
+ */
+export function criticalPathHits(files, criticalPaths = []) {
+    const hits = new Set();
+    for (const raw of files) {
+        const f = normPath(raw);
+        if (!f)
+            continue;
+        for (const rawCritical of criticalPaths) {
+            const critical = normPath(rawCritical);
+            if (!critical)
+                continue;
+            if (f === critical || picomatch(critical, { dot: true })(f) || picomatch(f, { dot: true })(critical)
+                || (GLOB_META_RE.test(f) && GLOB_META_RE.test(critical) && globsMayIntersect(f, critical))) {
+                hits.add(f);
+            }
+        }
+    }
+    return [...hits].sort();
+}
+// R3 (OBS-186): `review: false` here is a SECOND participation switch, and unlike review.policy it is
+// not monotone — it can omit the review gate from a task the path rules assigned `full`. Participation
+// is decided by paths, so the two are JOINED at the one seam that can still refuse the graph:
+// reviewParticipationErrors (src/compile/collateral.ts) fails compile when a shape's `review: false`
+// would demote a full-review task or silence a critical path. The key itself stays parseable (a run's
+// own config, the setup cockpit and the shipped template all round-trip it); what it can no longer do
+// is take effect behind the policy's back.
 const ShapeGateParticipationSchema = z
     .object({ acceptance: z.boolean().optional(), review: z.boolean().optional() })
     .passthrough()
@@ -157,7 +322,22 @@ export const TickmarkrConfigSchema = z.object({
     judge: z.object({ adapter: z.string(), model: z.string() }),
     // v1.53 T2: prefer — ordered reviewer preference (entry grammar: adapter | adapter:model, same as
     // routing.map.prefer). Reorders diversity-eligible channels only; never widens or narrows eligibility.
-    review: z.object({ complexityThreshold: z.number(), required: z.boolean(), prefer: z.array(z.string()).optional() }),
+    review: z.object({
+        // RETIRED as a participation switch (R3 / OBS-186, v1.85): review participation is decided by the
+        // paths a task declares and the paths its diff touches — never by complexity. The key survives
+        // because routing hints and the setup cockpit still read it as a complexity landmark; NOTHING in
+        // src/gates/review.ts reads it any more, and a value here can no longer disable a review.
+        complexityThreshold: z.number(),
+        required: z.boolean(),
+        prefer: z.array(z.string()).optional(),
+        // R3: the operator's participation floor. "full" forces a cross-vendor review on every task;
+        // "judge-only" is the neutral floor (it leaves the compiler's per-task assignment standing).
+        // Config may RAISE a task's policy and can never lower one — see raiseReviewPolicy.
+        policy: z.enum(REVIEW_POLICIES).optional(),
+        // R3: globs no task may skip review on (input/demux/lifecycle, gates/run/drivers/adapters, anything
+        // reaching a shell). A judge-only task intersecting one of these fails COMPILE, never silently skips.
+        criticalPaths: z.array(z.string()).optional(),
+    }),
     // v1.54 T1: prefer — ranked consult seat failover. Entries MUST be adapter:model (unlike
     // review.prefer's adapter|adapter:model grammar): a consult seat has no channel to inherit a
     // model from, so a bare adapter is meaningless and fails config load fail-closed. The pinned
@@ -188,6 +368,24 @@ export class ConfigError extends Error {
         this.name = "ConfigError";
     }
 }
+function assertSeededModelWindows() {
+    const cited = new Map(CITED_MODEL_WINDOWS.map((claim) => [claim.modelId, claim.window]));
+    for (const [adapter, entry] of Object.entries(DEFAULT_CONFIG.tiers)) {
+        for (const [model, window] of Object.entries(entry.windows ?? {})) {
+            const path = `tiers.${adapter}.windows.${model}`;
+            if (window < MODEL_WINDOW_PLAUSIBILITY_FLOOR) {
+                throw new ConfigError(`${path} declares window ${window}, below plausibility floor ${MODEL_WINDOW_PLAUSIBILITY_FLOOR} (non-authoritative rejection guard)`);
+            }
+            const citedWindow = cited.get(model);
+            if (citedWindow === undefined) {
+                throw new ConfigError(`${path} has no cited model-window entry in T20's vendored table`);
+            }
+            if (window !== citedWindow) {
+                throw new ConfigError(`${path} declares ${window} but does not match cited window ${citedWindow} in T20's vendored table`);
+            }
+        }
+    }
+}
 export const DEFAULT_CONFIG = {
     concurrency: 3,
     driver: "auto",
@@ -221,10 +419,13 @@ export const DEFAULT_CONFIG = {
         allowUnverifiedModels: false,
     },
     // Seed table (spec §13). New models = edit this (or your config.yaml), never code.
+    // Windows are copied rather than derived from T20's table so config load can reject disagreement
+    // between two independently owned artifacts instead of letting one side certify itself.
     tiers: {
         "claude-code": {
             vendor: "anthropic", channel: "sub",
             models: { fable: "frontier", opus: "frontier", sonnet: "mid", haiku: "cheap" },
+            windows: { fable: 1_000_000, opus: 1_000_000, sonnet: 1_000_000, haiku: 200_000 },
         },
         // ids verified against installed CLI models_cache.json (codex 0.144.0, fetched 2026-07-09);
         // gpt-5.4 / gpt-5.4-mini removed — OpenAI retirement 2026-07-23; sol=frontier / terra=mid / luna=cheap per OpenAI tier framing.
@@ -236,6 +437,7 @@ export const DEFAULT_CONFIG = {
         codex: {
             vendor: "openai", channel: "sub",
             models: { "gpt-5.6-sol": "frontier", "gpt-5.5": "frontier", "gpt-5.6-terra": "mid", "gpt-5.6-luna": "cheap" },
+            windows: { "gpt-5.6-sol": 1_050_000, "gpt-5.5": 1_050_000, "gpt-5.6-terra": 1_050_000, "gpt-5.6-luna": 1_050_000 },
         },
         // grok-4.5 (xAI, released 2026-07-08) → mid: AA Intelligence 54 (#4), Terminal-Bench 2.1 83.3%
         // (≈ GPT-5.5 83.4, Fable 5 84.3), SWE-bench Pro 64.7%, ~4.2× more token-efficient than Opus 4.8
@@ -256,6 +458,7 @@ export const DEFAULT_CONFIG = {
                 // stop burning its mid. Operator-approved 2026-07-16.
                 "composer-2.5-fast": "cheap",
             },
+            windows: { "composer-2.5": 200_000, "composer-2.5-fast": 200_000 },
         },
         // GLM-5.2 → mid per benchmark policy (2026-07): SWE-bench Pro 62.1 (> GPT-5.5 58.6), FrontierSWE 74.4 ≈ Opus 4.8;
         // no independent Terminal-Bench score → conservative mid, overlays may raise.
@@ -266,6 +469,7 @@ export const DEFAULT_CONFIG = {
         opencode: {
             vendor: "mixed", channel: "sub",
             models: { "zai-coding-plan/glm-5.2": "mid" },
+            windows: { "zai-coding-plan/glm-5.2": 1_000_000 },
         },
         // GLM-5.2 via pi/ZAI Coding Plan (sub, flat-rate). mid per benchmark policy (2026-07):
         // SWE-bench Pro 62.1, FrontierSWE 74.4 — same rationale as the opencode glm-5.2 seed above.
@@ -277,6 +481,7 @@ export const DEFAULT_CONFIG = {
         pi: {
             vendor: "zhipu", channel: "sub",
             models: { "zai/glm-5.2": "mid" },
+            windows: { "zai/glm-5.2": 1_000_000 },
         },
         // Native grok CLI (Phase 40). grok-4.5 → mid: same benchmark provenance as the retired cursor-agent
         // grok-4.5-xhigh seed above (AA 54, TB2.1 83.3%, SWE-b Pro 64.7% — researched 2026-07-10).
@@ -286,6 +491,7 @@ export const DEFAULT_CONFIG = {
         grok: {
             vendor: "xai", channel: "sub",
             models: { "grok-4.5": "mid", "grok-composer-2.5-fast": "cheap" },
+            windows: { "grok-4.5": 500_000, "grok-composer-2.5-fast": 200_000 },
         },
         // Native kimi CLI (Phase 48). kimi-code/k3 → frontier: 81.2 FrontierSWE, 88.3 Terminal-Bench 2.1,
         // top-3 across six coding benchmarks (research 2026-07-17, K3 released 2026-07-16).
@@ -298,18 +504,25 @@ export const DEFAULT_CONFIG = {
                 "kimi-code/kimi-for-coding": "mid",
                 "kimi-code/kimi-for-coding-highspeed": "cheap",
             },
+            windows: {
+                "kimi-code/k3": 1_048_576,
+                "kimi-code/kimi-for-coding": 262_144,
+                "kimi-code/kimi-for-coding-highspeed": 262_144,
+            },
         },
     },
     pricing: { cheap: 0.1, mid: 0.5, frontier: 2.5 },
     gates: { diffCap: DEFAULT_DIFF_CAP },
     judge: { adapter: "claude-code", model: "fable" },
-    review: { complexityThreshold: 7, required: true },
+    // R3: no `policy` floor — the neutral floor leaves the compiler's per-task assignment standing, so
+    // the path-keyed rule is reachable out of the box rather than raised to full by construction.
+    review: { complexityThreshold: 7, required: true, criticalPaths: [...DEFAULT_REVIEW_CRITICAL_PATHS] },
     consult: { adapter: "claude-code", model: "fable", stallMinutes: 15 },
     // v1.4: gate LLM calls (judge/review/consult) run headless by default; pane opts back into visible agents.
     // v1.2: workers are the real agent TUI in the pane; "print" restores the -p-rendered-in-pane path.
     visibility: { llm: "headless", keepPanes: "run", worker: "interactive", workersPerTab: 3 },
 };
-function deepMerge(base, over) {
+function deepMerge(base, over, path = []) {
     if (over === undefined || over === null)
         return base;
     if (Array.isArray(base) || Array.isArray(over) || typeof base !== "object" || typeof over !== "object" || base === null) {
@@ -318,12 +531,18 @@ function deepMerge(base, over) {
     const out = { ...base };
     for (const [k, v] of Object.entries(over)) {
         if (v === null) {
-            delete out[k]; // v1.1 tombstone: an explicit null in an overlay removes the key (e.g. stale tiers model ids)
+            // T19: null is a declared multi-vendor state only at tiers.<adapter>.vendor. Every other null
+            // remains the v1.1 overlay tombstone (for example a stale tiers model id).
+            if (path.length === 2 && path[0] === "tiers" && k === "vendor")
+                out[k] = null;
+            else
+                delete out[k];
             continue;
         }
         // OBS-75 class: merge fresh-landing objects onto {} so nested tombstone nulls are pruned even when
         // no lower layer set the key (a fleet-cleared deny writes {adapters: null} — the schema rejects raw null)
-        out[k] = k in out ? deepMerge(out[k], v) : deepMerge({}, v);
+        const childPath = [...path, k];
+        out[k] = k in out ? deepMerge(out[k], v, childPath) : deepMerge({}, v, childPath);
     }
     return out;
 }
@@ -401,7 +620,7 @@ function resolveRoutingMode(cfg, layers) {
                 lints.push(`floors.${shape}: ${val} (config floors) overrides mode ${mode} — shadowed delta: ${shape} ${dflt}→${moded}`);
             }
             if (TIER_RANK[val] < TIER_RANK[integrityMin(shape)]) {
-                lints.push(`floors.${shape}: ${val} is below integrity minimum frontier — integrity class ${INTEGRITY_FLOOR_SHAPES.join("/")} holds regardless of mode`);
+                lints.push(`floors.${shape}: ${val} is below integrity minimum frontier — integrity class ${INTEGRITY_FLOOR_SHAPES.join("/")} is advisory to explicit floors and map pins; map pins are supreme`);
             }
             continue;
         }
@@ -431,6 +650,9 @@ export function loadConfigWithMode(repoRoot, opts = {}) {
     const r = TickmarkrConfigSchema.safeParse(merged);
     if (!r.success)
         throw new ConfigError(z.prettifyError(r.error));
+    // The vendored table attests Tickmarkr's built-in seed artifact. Operator overlays remain free to
+    // declare private/future models and deliberately smaller test windows without pretending T20 cited them.
+    assertSeededModelWindows();
     return { cfg: r.data, mode: resolveRoutingMode(r.data, [globalCfg, repoCfg]) };
 }
 export function loadConfig(repoRoot, opts = {}) {
@@ -487,7 +709,7 @@ export function configTemplate(overlay) {
 #   llm: headless         # headless (default): judge/review/consult run silently | pane: visible agents
 #   keepPanes: run        # run (default): ephemeral judge/review/consult panes close when read; a merged task's worker pane closes on done; other worker panes persist until run end | attempt | forever (keep everything for debugging)
 #   worker: interactive   # interactive (default): workers run the real agent TUI | print
-#   workersPerTab: 3      # cap concurrent worker panes per WORKERS tab; overflow opens WORKERS-2 (VIS-09). Default 3
+#   workersPerTab: 3      # cap worker panes sharing one tab; gate panes ride with their task and never count. Default 3
 # scope:
 #   allowDeviations: []    # globs an operator permits out-of-scope edits into, e.g. ["package-lock.json"]
 # gates:                  # override auto-detected commands; per-shape participation may only skip LLM gates
@@ -541,9 +763,8 @@ export function configTemplate(overlay) {
     const nl = base.indexOf("\n");
     return `${base.slice(0, nl + 1)}${lines.join("\n")}\n${base.slice(nl + 1)}`;
 }
-// v1.61 seed 8: the fleet-overlay provenance cluster (harvesting, serialization, diff rendering)
-// moved to fleet-overlay.ts as a pure move — re-exported here so prior import paths keep working.
-export { FLEET_OVERLAY_KEYS, fleetEditableEquals, fleetRepoOverlayFromDelta, harvestFleetProvenance, repoOverlayYaml, serializeFleetOverlay, unifiedYamlDiff, } from "./fleet-overlay.js";
+// Fleet overlay mutation, legacy serialization, and diff rendering live together in fleet-overlay.ts.
+export { FLEET_OVERLAY_KEYS, fleetEditableEquals, fleetRepoOverlayFromDelta, renderFleetOverlayWrite, repoOverlayYaml, serializeFleetOverlay, unifiedYamlDiff, } from "./fleet-overlay.js";
 export function repoOverlayPath(repoRoot) {
     return join(repoRoot, stateDirName(repoRoot), "config.yaml");
 }
@@ -555,15 +776,12 @@ export function readOverlayFile(path) {
         throw new ConfigError(`invalid overlay at ${path}`);
     return raw;
 }
-export function fleetEditableFromConfig(cfg, provenance = {}) {
+export function fleetEditableFromConfig(cfg) {
     const tiers = {};
     for (const [adapter, entry] of Object.entries(cfg.tiers)) {
         tiers[adapter] = {};
         for (const [model, tier] of Object.entries(entry.models)) {
-            // OBS-88: notes harvested from the overlay ride the session state from load, so a later
-            // write knows about every existing note — not only the ones this session typed itself
-            const note = provenance[adapter]?.[model];
-            tiers[adapter][model] = note ? { tier, provenance: note } : { tier };
+            tiers[adapter][model] = { tier };
         }
     }
     return {
@@ -599,55 +817,24 @@ export function fleetKeyLayer(repoRoot, dotted, opts = {}) {
 export function formatFleetPrint(repoRoot, opts = {}) {
     const gdir = opts.globalDir ?? globalConfigDir();
     const effective = loadConfig(repoRoot, { globalDir: gdir });
-    const editable = fleetEditableFromConfig(effective);
-    const lines = ["# tickmarkr fleet — effective state (repo > global > defaults)"];
-    const annotate = (dotted, yaml) => `${yaml}  # ${fleetKeyLayer(repoRoot, dotted, opts)}`;
-    const denyAdapters = editable.denyAdapters;
-    const denyModels = editable.denyModels;
-    if (denyAdapters.length || denyModels.length) {
-        lines.push("routing:");
-        lines.push("  deny:");
-        if (denyAdapters.length)
-            lines.push(annotate("routing.deny.adapters", `    adapters: ${stringify(denyAdapters).trim()}`));
-        if (denyModels.length)
-            lines.push(annotate("routing.deny.models", `    models: ${stringify(denyModels).trim()}`));
-    }
-    const mapKeys = Object.keys(editable.map).sort();
-    if (mapKeys.length) {
-        if (!lines.some((l) => l === "routing:"))
-            lines.push("routing:");
-        lines.push("  map:");
-        for (const shape of mapKeys) {
-            const entry = editable.map[shape];
-            const body = stringify(entry, { indent: 4 }).trim().split("\n").map((l) => `    ${l}`).join("\n");
-            lines.push(annotate(`routing.map.${shape}`, `    ${shape}:`));
-            lines.push(body.split("\n").slice(1).join("\n"));
-        }
-    }
-    const floorKeys = Object.keys(editable.floors).sort();
-    if (floorKeys.length) {
-        if (!lines.some((l) => l === "routing:"))
-            lines.push("routing:");
-        lines.push(annotate("routing.floors", `  floors: ${stringify(Object.fromEntries(floorKeys.map((k) => [k, editable.floors[k]]))).trim().replace(/^/gm, "  ")}`));
-    }
-    const tierAdapters = Object.keys(editable.tiers).sort();
-    if (tierAdapters.length) {
-        lines.push("tiers:");
-        for (const adapter of tierAdapters) {
-            const models = editable.tiers[adapter];
-            const modelIds = Object.keys(models).sort();
-            if (!modelIds.length)
-                continue;
-            lines.push(`  ${adapter}:`);
-            lines.push("    models:");
-            for (const model of modelIds) {
-                const v = models[model];
-                if (v === null)
-                    lines.push(`      ${model}: null`);
-                else
-                    lines.push(annotate(`tiers.${adapter}.models.${model}`, `      ${model}: ${v.tier}`));
-            }
+    const doc = new Document({ routing: effective.routing, tiers: effective.tiers });
+    doc.commentBefore = " tickmarkr fleet — effective state (repo > global > defaults)";
+    const annotate = (path, dotted = path.join(".")) => {
+        const node = doc.getIn(path, true);
+        if (node && typeof node === "object" && "comment" in node) {
+            node.comment = ` ${fleetKeyLayer(repoRoot, dotted, opts)}`;
         }
+    };
+    if (effective.routing.deny?.adapters !== undefined)
+        annotate(["routing", "deny", "adapters"]);
+    if (effective.routing.deny?.models !== undefined)
+        annotate(["routing", "deny", "models"]);
+    for (const shape of Object.keys(effective.routing.map))
+        annotate(["routing", "map", shape]);
+    annotate(["routing", "floors"]);
+    for (const [adapter, entry] of Object.entries(effective.tiers)) {
+        for (const model of Object.keys(entry.models))
+            annotate(["tiers", adapter, "models", model]);
     }
-    return `${lines.join("\n")}\n`;
+    return String(doc);
 }

package/dist/config/fleet-overlay.d.ts

@@ -1,27 +1,32 @@
-import type { FleetEditable } from "./config.js";
+import type { FleetEditable, RoutingMode } from "./config.js";
 /** Fleet-owned overlay keys — the only config surface `tickmarkr fleet` may write. */
 export declare const FLEET_OVERLAY_KEYS: readonly ["routing", "tiers"];
-/** Trailing `# note` comments on per-entry lines an operator may have hand-written or a prior
- *  fleet write stamped: model tier lines (including null tombstones) and deny list items. */
-export type HarvestedProvenance = {
-    tiers: Record<string, Record<string, string>>;
-    denyAdapters: Record<string, string>;
-    denyModels: Record<string, string>;
+export type FleetOverlayWrite = {
+    initial: FleetEditable;
+    edited: FleetEditable;
+    mode?: RoutingMode;
+    steering?: {
+        initial: {
+            review?: string[];
+            consult?: string[];
+        };
+        edited: {
+            review?: string[];
+            consult?: string[];
+        };
+    };
 };
-/** OBS-88: harvest existing provenance comments from raw repo-overlay bytes at fleet-session
- *  load. yaml.parse discards comments, so before this every fleet write re-serialized the file
- *  knowing only the current session's own notes and silently stripped all prior ones — a typed
- *  benchmark-provenance note survived exactly one write. Fail-open to empty: an unreadable
- *  overlay is the loader's problem to reject, never the harvester's. */
-export declare function harvestFleetProvenance(overlayText: string): HarvestedProvenance;
-/** Harvested deny-entry notes keyed by the exact entry string, re-attached at serialize time. */
-export type FleetDenyNotes = {
-    adapters?: Record<string, string>;
-    models?: Record<string, string>;
+export type FleetFirstTouch = {
+    vendor: string;
+    channel: "sub" | "api";
 };
+export declare function fleetFirstTouchProvenance(note: string, firstTouch: FleetFirstTouch): string;
+/** Apply only fields fleet authored to the parsed YAML document. Untouched nodes retain their
+ * keys, ordering, scalar style, and comments; fresh provenance is written directly on its tier node. */
+export declare function renderFleetOverlayWrite(priorBytes: string, write: FleetOverlayWrite): string;
 /** Build the repo overlay fragment fleet would write for edits since session start. */
-export declare function fleetRepoOverlayFromDelta(initial: FleetEditable, edited: FleetEditable, existingRepo?: Record<string, unknown>): Record<string, unknown>;
-export declare function repoOverlayYaml(overlay: Record<string, unknown>, provenance?: Record<string, Record<string, string>>, denyNotes?: FleetDenyNotes): string;
-export declare function serializeFleetOverlay(overlay: Record<string, unknown>, provenance?: Record<string, Record<string, string>>, denyNotes?: FleetDenyNotes): string;
+export declare function fleetRepoOverlayFromDelta(initial: FleetEditable, edited: FleetEditable, existingRepo?: Record<string, unknown>, firstTouches?: Readonly<Record<string, FleetFirstTouch>>): Record<string, unknown>;
+export declare function repoOverlayYaml(overlay: Record<string, unknown>): string;
+export declare function serializeFleetOverlay(overlay: Record<string, unknown>): string;
 export declare function unifiedYamlDiff(before: string, after: string, label?: string): string;
 export declare function fleetEditableEquals(a: FleetEditable, b: FleetEditable): boolean;