tickmarkr 1.60.0 → 1.61.0

package/README.md

@@ -160,9 +160,9 @@ Nothing is written until you confirm; pressing Enter through every step leaves c
 Step 5/6 uses an arrow-driven candidate picker ranked by the production router; step 3 may ask
 for a benchmark-provenance note when you classify a new model.
 
-Routing-mode semantics, pin/prefer/floor precedence, review and consult steering syntax,
+Routing-mode semantics, pin/floor/prefer precedence, review and consult steering syntax,
 provenance rules, and `--quality` / `--mode` flags are documented in
-**[FLEET.md](FLEET.md)** (advanced reference).
+**[FLEET.md](https://github.com/alzahrani-khalid/tickmarkr/blob/main/FLEET.md)** (advanced reference).
 
 ## Steering
 
@@ -170,7 +170,7 @@ Fleet step 6/6 sets `review.prefer` and `consult.prefer`; routing modes (`risk-b
 `partner-led`, `staff-led`) are chosen in step 4/6. Full grammar — including when review
 prefer may name a **bare adapter** versus `adapter:model`, and why consult prefer entries
 require **`adapter:model`** form — plus `tickmarkr run --supersedes` rerun control, is in
-**[FLEET.md](FLEET.md)**.
+**[FLEET.md](https://github.com/alzahrani-khalid/tickmarkr/blob/main/FLEET.md)**.
 
 ## Model scoping and auth detection
 
@@ -366,7 +366,7 @@ accepted contributions are credited via `Co-authored-by:` on the release commit.
 
 ## Documentation
 
-- **[FLEET.md](FLEET.md)** — routing modes, steering syntax, tier provenance, and run flags (advanced reference)
+- **[FLEET.md](https://github.com/alzahrani-khalid/tickmarkr/blob/main/FLEET.md)** — routing modes, steering syntax, tier provenance, and run flags (advanced reference)
 - **[LICENSE](LICENSE)** — MIT license
 - **[CONTRIBUTING.md](CONTRIBUTING.md)** — development setup and contribution guidelines
 - **[SECURITY.md](SECURITY.md)** — security policy and private vulnerability reporting

package/dist/cli/commands/status.js

@@ -67,6 +67,11 @@ const failedSuffix = (states) => {
     const f = failedGates(states);
     return f.length ? ` · ${f.join(", ")}` : "";
 };
+// a designed human gate parks the task BEFORE any gate result exists (daemon.ts execTask), so the
+// awaited approval is named from task state alone — never from gate results. Failed gates win the
+// cell when present: a post-approval park is not awaiting the designed gate. Plain text for column
+// math; rendered with a dim dot + warn words. TTY-only — the non-TTY surface stays byte-pinned.
+const humanGateSuffix = (t, st, states) => st === "human" && t.humanGate && failedGates(states).length === 0 ? " · awaiting approval" : "";
 const shortGoal = (goal, max) => {
     const clause = goal.split(/[,;.?!]/, 1)[0].trim();
     if (clause.length <= max)
@@ -203,7 +208,7 @@ const renderFrame = (cwd) => {
     const gatesLegend = legend(`   gates: ${GATE_NAMES.join(" · ")}`);
     const taskVerdict = (st) => st === "done" ? "pass" : st === "failed" ? "fail" : st === "human" ? "warn" : "neutral";
     const idW = Math.max(...cells.map((c) => c.t.id.length), 2);
-    const stW = Math.max(...cells.map((c) => (String(c.st) + c.label + failedSuffix(c.states)).length));
+    const stW = Math.max(...cells.map((c) => (String(c.st) + c.label + failedSuffix(c.states) + humanGateSuffix(c.t, c.st, c.states)).length));
     const chainW = gateChainWidth(true);
     const assignW = Math.max(...cells.map((c) => c.assignCol.length));
     const goalW = Math.max(8, width - (5 + idW) - 2 - chainW - 2 - stW - 2 - assignW);
@@ -212,10 +217,12 @@ const renderFrame = (cwd) => {
         const stWord = st === "done" ? ok(String(st)) : st === "failed" ? fail(String(st)) : st === "human" ? warn(String(st)) : String(st);
         // a fail names its gate in words right here — the one moment gate identity is needed on a row
         const f = failedGates(states);
+        const human = humanGateSuffix(t, st, states);
         const statusCell = stWord +
             (label ? (label === " starved" ? fail(label) : dim(label)) : "") +
             (f.length ? dim(" · ") + fail(f.join(", ")) : "") +
-            " ".repeat(stW - (String(st) + label + failedSuffix(states)).length);
+            (human ? dim(" · ") + warn("awaiting approval") : "") +
+            " ".repeat(stW - (String(st) + label + failedSuffix(states) + human).length);
         return `  ${statusRow(taskVerdict(st), `${t.id.padEnd(idW)} ${goal}  ${gateChain(states, true)}  ${statusCell}  ${dim(assignCol)}`)}`;
     });
     return [header, hr, gatesLegend, ...rows].join("\n");

package/dist/compile/native.d.ts

@@ -1,4 +1,5 @@
 import { type RunGraph } from "../graph/schema.js";
+export declare const COLLECTABLE_TESTS = "tests/**/*.test.ts";
 export declare const LEGACY_PREFIX: string;
 export declare const TICKMARKR_NATIVE_MARKER: RegExp;
 export declare const NATIVE_MARKER: RegExp;

package/dist/compile/native.js

@@ -1,6 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
+import picomatch from "picomatch";
 import { GATE_NAMES, GRAPH_ROUTING_MODES, ORACLES, SHAPES, TIERS, validateGraph } from "../graph/schema.js";
 import { CompileError, inferShape, sha256 } from "./common.js";
+// OBS-97: mirror of the vitest.config.ts suite include — the only path class vitest collects.
+export const COLLECTABLE_TESTS = "tests/**/*.test.ts";
 export const LEGACY_PREFIX = ["dro", "vr"].join("");
 export const TICKMARKR_NATIVE_MARKER = /^<!--\s*tickmarkr:spec(?:\s+v1)?\s*-->\s*$/m;
 export const NATIVE_MARKER = new RegExp(`^<!--\\s*(?:tickmarkr|${LEGACY_PREFIX}):spec(?:\\s+v1)?\\s*-->\\s*$`, "m");
@@ -116,6 +119,35 @@ export function compileNative(file) {
             `Add to each section in ${file}:\n- acceptance:\n  - <observable outcome>`);
     }
     const csv = (value) => (value && value.toLowerCase() !== "none" ? value.split(",").map((item) => item.trim()).filter(Boolean) : []);
+    // OBS-97: a typed test: oracle needs a collectable home. vitest only collects COLLECTABLE_TESTS
+    // paths, so a task whose non-empty files[] cannot host one makes scope-green and acceptance-green
+    // mutually exclusive by construction — run-20260719-210434 burned two dispatch attempts before a
+    // consult diagnosed exactly this. Empty files[] stays exempt: no file scope means unrestricted
+    // (src/gates/scope.ts). An entry hosts a collectable path iff its glob can produce one — probed by
+    // substituting each wildcard run with a test-shaped segment (also covers literal test-file paths).
+    const collectable = picomatch(COLLECTABLE_TESTS, { dot: true });
+    // Single-token substitution is not a true glob-overlap test (tests/**/*.ts needs "probe.test",
+    // a bare ** needs the whole collectable path) — probe with several test-shaped tokens and accept
+    // if ANY candidate satisfies both globs. Scopes that truly cannot host one still fail every probe.
+    const PROBE_TOKENS = ["probe.test.ts", "probe.test", "tests/probe.test.ts"];
+    const canHostTest = (entry) => {
+        const self = picomatch(entry, { dot: true });
+        return PROBE_TOKENS.some((token) => {
+            const probe = entry.replace(/\*+/g, token);
+            return self(probe) && collectable(probe);
+        });
+    };
+    const homeless = drafts
+        .filter((draft) => {
+        const files = csv(draft.fields.files);
+        return files.length > 0 && !files.some(canHostTest)
+            && draft.acceptance.some((item) => typeof item !== "string" && item.oracle === "test");
+    })
+        .map((draft) => draft.id);
+    if (homeless.length) {
+        throw new CompileError(`OBS-97: task${homeless.length === 1 ? "" : "s"} ${homeless.join(", ")} carr${homeless.length === 1 ? "ies" : "y"} a test: acceptance oracle but files[] cannot host a vitest-collectable test path (${COLLECTABLE_TESTS}).\n` +
+            `Add a ${COLLECTABLE_TESTS} entry to files[] in ${file}, or replace the test: oracle with command:/judge:.`);
+    }
     const tasks = drafts.map((draft) => {
         const { fields } = draft;
         const shape = fields.shape ?? inferShape(draft.title);

package/dist/config/config.d.ts

@@ -235,8 +235,8 @@ export type InitConfigOverlay = {
     };
 };
 export declare function configTemplate(overlay?: InitConfigOverlay): string;
-/** Fleet-owned overlay keys — the only config surface `tickmarkr fleet` may write. */
-export declare const FLEET_OVERLAY_KEYS: readonly ["routing", "tiers"];
+export { FLEET_OVERLAY_KEYS, fleetEditableEquals, fleetRepoOverlayFromDelta, harvestFleetProvenance, repoOverlayYaml, serializeFleetOverlay, unifiedYamlDiff, } from "./fleet-overlay.js";
+export type { FleetDenyNotes, HarvestedProvenance } from "./fleet-overlay.js";
 export type FleetTierAssignment = {
     tier: Tier;
     provenance?: string;
@@ -259,28 +259,3 @@ export declare function fleetKeyLayer(repoRoot: string, dotted: string, opts?: {
 export declare function formatFleetPrint(repoRoot: string, opts?: {
     globalDir?: string;
 }): string;
-/** 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>;
-};
-/** 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>;
-};
-/** 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 unifiedYamlDiff(before: string, after: string, label?: string): string;
-export declare function fleetEditableEquals(a: FleetEditable, b: FleetEditable): boolean;
-export {};

package/dist/config/config.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { isMap, isScalar, isSeq, parse, parseDocument, stringify } from "yaml";
+import { parse, stringify } from "yaml";
 import { z } from "zod";
 import { stateDirName } from "../graph/graph.js";
 import { SHAPES, TIERS } from "../graph/schema.js";
@@ -533,8 +533,9 @@ export function configTemplate(overlay) {
     const nl = base.indexOf("\n");
     return `${base.slice(0, nl + 1)}${lines.join("\n")}\n${base.slice(nl + 1)}`;
 }
-/** Fleet-owned overlay keys — the only config surface `tickmarkr fleet` may write. */
-export const FLEET_OVERLAY_KEYS = ["routing", "tiers"];
+// 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";
 export function repoOverlayPath(repoRoot) {
     return join(repoRoot, stateDirName(repoRoot), "config.yaml");
 }
@@ -565,14 +566,6 @@ export function fleetEditableFromConfig(cfg, provenance = {}) {
         floors: { ...cfg.routing.floors },
     };
 }
-function fleetSubset(obj) {
-    const out = {};
-    for (const k of FLEET_OVERLAY_KEYS) {
-        if (obj[k] !== undefined)
-            out[k] = obj[k];
-    }
-    return out;
-}
 /** Resolve which layer last set a dotted fleet path (defaults < global < repo). */
 export function fleetKeyLayer(repoRoot, dotted, opts = {}) {
     const gdir = opts.globalDir ?? globalConfigDir();
@@ -650,238 +643,3 @@ export function formatFleetPrint(repoRoot, opts = {}) {
     }
     return `${lines.join("\n")}\n`;
 }
-function sortedUnique(xs) {
-    return [...new Set(xs)].sort();
-}
-/** 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 function harvestFleetProvenance(overlayText) {
-    const out = { tiers: {}, denyAdapters: {}, denyModels: {} };
-    if (!overlayText.trim())
-        return out;
-    const doc = parseDocument(overlayText);
-    const note = (n) => {
-        const c = isScalar(n) ? n.comment : undefined;
-        return typeof c === "string" && c.trim() ? c.trim() : undefined;
-    };
-    const tiers = doc.getIn(["tiers"]);
-    if (isMap(tiers)) {
-        for (const ap of tiers.items) {
-            if (!isScalar(ap.key))
-                continue;
-            const models = isMap(ap.value) ? ap.value.get("models") : undefined;
-            if (!isMap(models))
-                continue;
-            for (const mp of models.items) {
-                const n = note(mp.value);
-                if (isScalar(mp.key) && n)
-                    (out.tiers[String(ap.key.value)] ??= {})[String(mp.key.value)] = n;
-            }
-        }
-    }
-    for (const [key, dest] of [["adapters", out.denyAdapters], ["models", out.denyModels]]) {
-        const seq = doc.getIn(["routing", "deny", key]);
-        if (!isSeq(seq))
-            continue;
-        for (const item of seq.items) {
-            const n = note(item);
-            if (isScalar(item) && n)
-                dest[String(item.value)] = n;
-        }
-    }
-    return out;
-}
-/** Build the repo overlay fragment fleet would write for edits since session start. */
-export function fleetRepoOverlayFromDelta(initial, edited, existingRepo = {}) {
-    if (fleetEditableEquals(initial, edited))
-        return {};
-    const out = structuredClone(existingRepo);
-    const routing = { ...out.routing };
-    let routingTouched = false;
-    const denyChanged = sortedUnique(initial.denyAdapters).join() !== sortedUnique(edited.denyAdapters).join()
-        || sortedUnique(initial.denyModels).join() !== sortedUnique(edited.denyModels).join();
-    if (denyChanged) {
-        routing.deny = {
-            adapters: edited.denyAdapters.length ? edited.denyAdapters : null,
-            models: edited.denyModels.length ? edited.denyModels : null,
-        };
-        routingTouched = true;
-    }
-    const mapDelta = {};
-    for (const shape of new Set([...Object.keys(initial.map), ...Object.keys(edited.map)])) {
-        if (JSON.stringify(initial.map[shape]) !== JSON.stringify(edited.map[shape]))
-            mapDelta[shape] = edited.map[shape];
-    }
-    if (Object.keys(mapDelta).length) {
-        routing.map = { ...routing.map, ...mapDelta };
-        routingTouched = true;
-    }
-    const floorDelta = {};
-    for (const shape of new Set([...Object.keys(initial.floors), ...Object.keys(edited.floors)])) {
-        if (initial.floors[shape] !== edited.floors[shape])
-            floorDelta[shape] = edited.floors[shape];
-    }
-    if (Object.keys(floorDelta).length) {
-        routing.floors = { ...routing.floors, ...floorDelta };
-        routingTouched = true;
-    }
-    if (routingTouched)
-        out.routing = routing;
-    const tiersOut = {
-        ...out.tiers,
-    };
-    let tiersTouched = false;
-    const adapters = new Set([...Object.keys(initial.tiers), ...Object.keys(edited.tiers)]);
-    for (const adapter of adapters) {
-        const models = new Set([
-            ...Object.keys(initial.tiers[adapter] ?? {}),
-            ...Object.keys(edited.tiers[adapter] ?? {}),
-        ]);
-        const modelDelta = {};
-        for (const model of models) {
-            const a = initial.tiers[adapter]?.[model];
-            const b = edited.tiers[adapter]?.[model];
-            if (JSON.stringify(a) !== JSON.stringify(b)) {
-                modelDelta[model] = b === null || b === undefined ? null : b.tier;
-            }
-        }
-        if (Object.keys(modelDelta).length) {
-            // spread the existing entry so vendor/channel/windows survive the rewrite — dropping them
-            // makes the overlay unloadable for any adapter without a default seed (reload-guard class)
-            tiersOut[adapter] = { ...tiersOut[adapter], models: { ...tiersOut[adapter]?.models, ...modelDelta } };
-            tiersTouched = true;
-        }
-    }
-    if (tiersTouched)
-        out.tiers = tiersOut;
-    return out;
-}
-export function repoOverlayYaml(overlay, provenance = {}, denyNotes = {}) {
-    if (!Object.keys(overlay).length)
-        return "";
-    const fleet = fleetSubset(overlay);
-    const fleetBody = serializeFleetOverlay(fleet, provenance, denyNotes);
-    const rest = { ...overlay };
-    for (const k of FLEET_OVERLAY_KEYS)
-        delete rest[k];
-    if (!Object.keys(rest).length)
-        return fleetBody;
-    const head = stringify(rest).trimEnd();
-    return fleetBody ? `${head}\n${fleetBody}` : `${head}\n`;
-}
-export function serializeFleetOverlay(overlay, provenance = {}, denyNotes = {}) {
-    if (!Object.keys(overlay).length)
-        return "";
-    const lines = [];
-    // OBS-75: never glue stringify() output onto a key line — wrap the key into the object and
-    // re-indent the whole emitted block, so sequences/nested maps nest correctly and null
-    // tombstones/empty collections survive the serialize→parse round-trip.
-    const block = (obj, pad) => stringify(obj).trimEnd().split("\n").map((l) => `${pad}${l}`);
-    // deny lists emit item-by-item through the same stringify quoting rules as block(), so a
-    // harvested `# reason` can re-attach to its exact entry (multi-line emissions never take one)
-    const denySeq = (key, v) => {
-        if (v === undefined)
-            return [];
-        if (v === null || !v.length)
-            return block({ [key]: v }, "    ");
-        const out = [`    ${key}:`];
-        for (const item of v) {
-            const emitted = stringify([item]).trimEnd().split("\n");
-            const n = denyNotes[key]?.[item];
-            if (n && emitted.length === 1)
-                emitted[0] += `  # ${n}`;
-            out.push(...emitted.map((l) => `      ${l}`));
-        }
-        return out;
-    };
-    const routing = overlay.routing;
-    if (routing) {
-        lines.push("routing:");
-        const deny = routing.deny;
-        if (deny && (deny.adapters !== undefined || deny.models !== undefined)) {
-            lines.push("  deny:");
-            lines.push(...denySeq("adapters", deny.adapters));
-            lines.push(...denySeq("models", deny.models));
-        }
-        if (routing.map)
-            lines.push(...block({ map: routing.map }, "  "));
-        if (routing.floors)
-            lines.push(...block({ floors: routing.floors }, "  "));
-    }
-    const tiers = overlay.tiers;
-    if (tiers && Object.keys(tiers).length) {
-        lines.push("tiers:");
-        for (const [adapter, entry] of Object.entries(tiers)) {
-            const body = [];
-            if (entry.vendor)
-                body.push(`    vendor: ${entry.vendor}`);
-            if (entry.channel)
-                body.push(`    channel: ${entry.channel}`);
-            if (entry.windows)
-                body.push(...block({ windows: entry.windows }, "    "));
-            const models = Object.entries(entry.models ?? {});
-            if (models.length) {
-                body.push("    models:");
-                for (const [model, tier] of models) {
-                    // OBS-88: notes serialize verbatim (fresh session notes arrive pre-stamped with their
-                    // "— fleet <date>" suffix), so a harvested note round-trips byte-for-byte every write
-                    const note = provenance[adapter]?.[model];
-                    const suffix = note ? `  # ${note}` : "";
-                    body.push(`      ${model}: ${tier === null ? "null" : tier}${suffix}`);
-                }
-            }
-            else if (entry.models) {
-                body.push("    models: {}"); // present-but-empty: explicit {} — a childless header parses as null and the loader rejects it
-            }
-            // a bare `adapter:` line parses as a null tombstone and would DELETE the adapter's default seeds on merge
-            if (body.length)
-                lines.push(`  ${adapter}:`, ...body);
-            else
-                lines.push(`  ${adapter}: {}`);
-        }
-    }
-    return `${lines.join("\n")}\n`;
-}
-export function unifiedYamlDiff(before, after, label = "config overlay") {
-    if (before === after)
-        return "";
-    const a = before.split("\n");
-    const b = after.split("\n");
-    // v1.60 T3: shortest-edit (LCS) matching. The old scan resynced greedily on the first mismatched
-    // line, so one inserted line could cascade into a whole-file remove/re-add hunk on the one
-    // confirmation surface an operator reviews before a write.
-    // ponytail: O(n·m) table — overlays are tens of lines; Myers O(nd) if files ever grow.
-    const lcs = Array.from({ length: a.length + 1 }, () => Array.from({ length: b.length + 1 }, () => 0));
-    for (let i = a.length - 1; i >= 0; i--) {
-        for (let j = b.length - 1; j >= 0; j--) {
-            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
-        }
-    }
-    const header = [`--- ${label} (current)`, `+++ ${label} (proposed)`];
-    const hunks = [];
-    let i = 0;
-    let j = 0;
-    while (i < a.length || j < b.length) {
-        if (i < a.length && j < b.length && a[i] === b[j]) {
-            i++;
-            j++;
-            continue;
-        }
-        const del = [];
-        const add = [];
-        while ((i < a.length || j < b.length) && !(i < a.length && j < b.length && a[i] === b[j])) {
-            if (j >= b.length || (i < a.length && lcs[i + 1][j] >= lcs[i][j + 1]))
-                del.push(`-${a[i++]}`);
-            else
-                add.push(`+${b[j++]}`);
-        }
-        hunks.push("@@", ...del, ...add);
-    }
-    return `${header.join("\n")}\n${hunks.join("\n")}\n`;
-}
-export function fleetEditableEquals(a, b) {
-    return JSON.stringify(a) === JSON.stringify(b);
-}

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

@@ -0,0 +1,27 @@
+import type { FleetEditable } 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>;
+};
+/** 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>;
+};
+/** 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 unifiedYamlDiff(before: string, after: string, label?: string): string;
+export declare function fleetEditableEquals(a: FleetEditable, b: FleetEditable): boolean;

package/dist/config/fleet-overlay.js

@@ -0,0 +1,249 @@
+// Fleet-overlay provenance cluster (v1.61 seed 8): harvesting, serialization, and diff rendering
+// for the `tickmarkr fleet` write path. Pure move out of config.ts — prior import paths preserved
+// via re-exports there.
+import { isMap, isScalar, isSeq, parseDocument, stringify } from "yaml";
+/** Fleet-owned overlay keys — the only config surface `tickmarkr fleet` may write. */
+export const FLEET_OVERLAY_KEYS = ["routing", "tiers"];
+function fleetSubset(obj) {
+    const out = {};
+    for (const k of FLEET_OVERLAY_KEYS) {
+        if (obj[k] !== undefined)
+            out[k] = obj[k];
+    }
+    return out;
+}
+function sortedUnique(xs) {
+    return [...new Set(xs)].sort();
+}
+/** 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 function harvestFleetProvenance(overlayText) {
+    const out = { tiers: {}, denyAdapters: {}, denyModels: {} };
+    if (!overlayText.trim())
+        return out;
+    const doc = parseDocument(overlayText);
+    const note = (n) => {
+        const c = isScalar(n) ? n.comment : undefined;
+        return typeof c === "string" && c.trim() ? c.trim() : undefined;
+    };
+    const tiers = doc.getIn(["tiers"]);
+    if (isMap(tiers)) {
+        for (const ap of tiers.items) {
+            if (!isScalar(ap.key))
+                continue;
+            const models = isMap(ap.value) ? ap.value.get("models") : undefined;
+            if (!isMap(models))
+                continue;
+            for (const mp of models.items) {
+                const n = note(mp.value);
+                if (isScalar(mp.key) && n)
+                    (out.tiers[String(ap.key.value)] ??= {})[String(mp.key.value)] = n;
+            }
+        }
+    }
+    for (const [key, dest] of [["adapters", out.denyAdapters], ["models", out.denyModels]]) {
+        const seq = doc.getIn(["routing", "deny", key]);
+        if (!isSeq(seq))
+            continue;
+        for (const item of seq.items) {
+            const n = note(item);
+            if (isScalar(item) && n)
+                dest[String(item.value)] = n;
+        }
+    }
+    return out;
+}
+/** Build the repo overlay fragment fleet would write for edits since session start. */
+export function fleetRepoOverlayFromDelta(initial, edited, existingRepo = {}) {
+    if (fleetEditableEquals(initial, edited))
+        return {};
+    const out = structuredClone(existingRepo);
+    const routing = { ...out.routing };
+    let routingTouched = false;
+    const denyChanged = sortedUnique(initial.denyAdapters).join() !== sortedUnique(edited.denyAdapters).join()
+        || sortedUnique(initial.denyModels).join() !== sortedUnique(edited.denyModels).join();
+    if (denyChanged) {
+        routing.deny = {
+            adapters: edited.denyAdapters.length ? edited.denyAdapters : null,
+            models: edited.denyModels.length ? edited.denyModels : null,
+        };
+        routingTouched = true;
+    }
+    const mapDelta = {};
+    for (const shape of new Set([...Object.keys(initial.map), ...Object.keys(edited.map)])) {
+        if (JSON.stringify(initial.map[shape]) !== JSON.stringify(edited.map[shape]))
+            mapDelta[shape] = edited.map[shape];
+    }
+    if (Object.keys(mapDelta).length) {
+        routing.map = { ...routing.map, ...mapDelta };
+        routingTouched = true;
+    }
+    const floorDelta = {};
+    for (const shape of new Set([...Object.keys(initial.floors), ...Object.keys(edited.floors)])) {
+        if (initial.floors[shape] !== edited.floors[shape])
+            floorDelta[shape] = edited.floors[shape];
+    }
+    if (Object.keys(floorDelta).length) {
+        routing.floors = { ...routing.floors, ...floorDelta };
+        routingTouched = true;
+    }
+    if (routingTouched)
+        out.routing = routing;
+    const tiersOut = {
+        ...out.tiers,
+    };
+    let tiersTouched = false;
+    const adapters = new Set([...Object.keys(initial.tiers), ...Object.keys(edited.tiers)]);
+    for (const adapter of adapters) {
+        const models = new Set([
+            ...Object.keys(initial.tiers[adapter] ?? {}),
+            ...Object.keys(edited.tiers[adapter] ?? {}),
+        ]);
+        const modelDelta = {};
+        for (const model of models) {
+            const a = initial.tiers[adapter]?.[model];
+            const b = edited.tiers[adapter]?.[model];
+            if (JSON.stringify(a) !== JSON.stringify(b)) {
+                modelDelta[model] = b === null || b === undefined ? null : b.tier;
+            }
+        }
+        if (Object.keys(modelDelta).length) {
+            // spread the existing entry so vendor/channel/windows survive the rewrite — dropping them
+            // makes the overlay unloadable for any adapter without a default seed (reload-guard class)
+            tiersOut[adapter] = { ...tiersOut[adapter], models: { ...tiersOut[adapter]?.models, ...modelDelta } };
+            tiersTouched = true;
+        }
+    }
+    if (tiersTouched)
+        out.tiers = tiersOut;
+    return out;
+}
+export function repoOverlayYaml(overlay, provenance = {}, denyNotes = {}) {
+    if (!Object.keys(overlay).length)
+        return "";
+    const fleet = fleetSubset(overlay);
+    const fleetBody = serializeFleetOverlay(fleet, provenance, denyNotes);
+    const rest = { ...overlay };
+    for (const k of FLEET_OVERLAY_KEYS)
+        delete rest[k];
+    if (!Object.keys(rest).length)
+        return fleetBody;
+    const head = stringify(rest).trimEnd();
+    return fleetBody ? `${head}\n${fleetBody}` : `${head}\n`;
+}
+export function serializeFleetOverlay(overlay, provenance = {}, denyNotes = {}) {
+    if (!Object.keys(overlay).length)
+        return "";
+    const lines = [];
+    // OBS-75: never glue stringify() output onto a key line — wrap the key into the object and
+    // re-indent the whole emitted block, so sequences/nested maps nest correctly and null
+    // tombstones/empty collections survive the serialize→parse round-trip.
+    const block = (obj, pad) => stringify(obj).trimEnd().split("\n").map((l) => `${pad}${l}`);
+    // deny lists emit item-by-item through the same stringify quoting rules as block(), so a
+    // harvested `# reason` can re-attach to its exact entry (multi-line emissions never take one)
+    const denySeq = (key, v) => {
+        if (v === undefined)
+            return [];
+        if (v === null || !v.length)
+            return block({ [key]: v }, "    ");
+        const out = [`    ${key}:`];
+        for (const item of v) {
+            const emitted = stringify([item]).trimEnd().split("\n");
+            const n = denyNotes[key]?.[item];
+            if (n && emitted.length === 1)
+                emitted[0] += `  # ${n}`;
+            out.push(...emitted.map((l) => `      ${l}`));
+        }
+        return out;
+    };
+    const routing = overlay.routing;
+    if (routing) {
+        lines.push("routing:");
+        const deny = routing.deny;
+        if (deny && (deny.adapters !== undefined || deny.models !== undefined)) {
+            lines.push("  deny:");
+            lines.push(...denySeq("adapters", deny.adapters));
+            lines.push(...denySeq("models", deny.models));
+        }
+        if (routing.map)
+            lines.push(...block({ map: routing.map }, "  "));
+        if (routing.floors)
+            lines.push(...block({ floors: routing.floors }, "  "));
+    }
+    const tiers = overlay.tiers;
+    if (tiers && Object.keys(tiers).length) {
+        lines.push("tiers:");
+        for (const [adapter, entry] of Object.entries(tiers)) {
+            const body = [];
+            if (entry.vendor)
+                body.push(`    vendor: ${entry.vendor}`);
+            if (entry.channel)
+                body.push(`    channel: ${entry.channel}`);
+            if (entry.windows)
+                body.push(...block({ windows: entry.windows }, "    "));
+            const models = Object.entries(entry.models ?? {});
+            if (models.length) {
+                body.push("    models:");
+                for (const [model, tier] of models) {
+                    // OBS-88: notes serialize verbatim (fresh session notes arrive pre-stamped with their
+                    // "— fleet <date>" suffix), so a harvested note round-trips byte-for-byte every write
+                    const note = provenance[adapter]?.[model];
+                    const suffix = note ? `  # ${note}` : "";
+                    body.push(`      ${model}: ${tier === null ? "null" : tier}${suffix}`);
+                }
+            }
+            else if (entry.models) {
+                body.push("    models: {}"); // present-but-empty: explicit {} — a childless header parses as null and the loader rejects it
+            }
+            // a bare `adapter:` line parses as a null tombstone and would DELETE the adapter's default seeds on merge
+            if (body.length)
+                lines.push(`  ${adapter}:`, ...body);
+            else
+                lines.push(`  ${adapter}: {}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function unifiedYamlDiff(before, after, label = "config overlay") {
+    if (before === after)
+        return "";
+    const a = before.split("\n");
+    const b = after.split("\n");
+    // v1.60 T3: shortest-edit (LCS) matching. The old scan resynced greedily on the first mismatched
+    // line, so one inserted line could cascade into a whole-file remove/re-add hunk on the one
+    // confirmation surface an operator reviews before a write.
+    // ponytail: O(n·m) table — overlays are tens of lines; Myers O(nd) if files ever grow.
+    const lcs = Array.from({ length: a.length + 1 }, () => Array.from({ length: b.length + 1 }, () => 0));
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--) {
+            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const header = [`--- ${label} (current)`, `+++ ${label} (proposed)`];
+    const hunks = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length || j < b.length) {
+        if (i < a.length && j < b.length && a[i] === b[j]) {
+            i++;
+            j++;
+            continue;
+        }
+        const del = [];
+        const add = [];
+        while ((i < a.length || j < b.length) && !(i < a.length && j < b.length && a[i] === b[j])) {
+            if (j >= b.length || (i < a.length && lcs[i + 1][j] >= lcs[i][j + 1]))
+                del.push(`-${a[i++]}`);
+            else
+                add.push(`+${b[j++]}`);
+        }
+        hunks.push("@@", ...del, ...add);
+    }
+    return `${header.join("\n")}\n${hunks.join("\n")}\n`;
+}
+export function fleetEditableEquals(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tickmarkr",
-  "version": "1.60.0",
+  "version": "1.61.0",
   "description": "Spec in, verified work out.",
   "type": "module",
   "license": "MIT",