tickmarkr 1.84.0 → 1.86.0

package/dist/config/fleet-overlay.js

@@ -1,6 +1,4 @@
-// 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.
+// Fleet-overlay mutation, serialization, and diff rendering for the `tickmarkr fleet` write path.
 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"];
@@ -15,49 +13,186 @@ function fleetSubset(obj) {
 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;
+// fleet.ts deliberately remains the sole overlay builder and writer. Its established classification
+// seam copies only `tier` and `note` into FleetEditable, so first-touch entry metadata rides inside a
+// private provenance envelope until this module writes the YAML. The envelope never reaches disk.
+const FIRST_TOUCH_OPEN = "\uE000tickmarkr-fleet-first-touch:";
+const FIRST_TOUCH_CLOSE = "\uE001";
+export function fleetFirstTouchProvenance(note, firstTouch) {
+    return `${FIRST_TOUCH_OPEN}${encodeURIComponent(firstTouch.vendor)}:${firstTouch.channel}${FIRST_TOUCH_CLOSE}${note}`;
+}
+function unpackFleetProvenance(provenance) {
+    if (!provenance?.startsWith(FIRST_TOUCH_OPEN))
+        return { provenance };
+    const close = provenance.indexOf(FIRST_TOUCH_CLOSE, FIRST_TOUCH_OPEN.length);
+    if (close === -1)
+        return { provenance };
+    const metadata = provenance.slice(FIRST_TOUCH_OPEN.length, close);
+    const colon = metadata.lastIndexOf(":");
+    if (colon === -1)
+        return { provenance };
+    const channel = metadata.slice(colon + 1);
+    if (channel !== "sub" && channel !== "api")
+        return { provenance };
+    try {
+        return {
+            provenance: provenance.slice(close + FIRST_TOUCH_CLOSE.length),
+            firstTouch: { vendor: decodeURIComponent(metadata.slice(0, colon)), channel },
+        };
+    }
+    catch {
+        return { provenance };
+    }
+}
+function setScalarPreservingComment(doc, path, value, authoredComment) {
+    const existing = doc.getIn(path, true);
+    if (isScalar(existing))
+        existing.value = value;
+    else
+        doc.setIn(path, doc.createNode(value));
+    if (authoredComment !== undefined) {
+        const written = doc.getIn(path, true);
+        if (isScalar(written))
+            written.comment = ` ${authoredComment}`;
+    }
+}
+function setStringSequencePreservingComments(doc, path, values) {
+    const existing = doc.getIn(path, true);
+    if (values === null) {
+        const tombstone = doc.createNode(null);
+        if (isScalar(tombstone) && existing && typeof existing === "object") {
+            // A block sequence's key-line note is stored as commentBefore; on a scalar it must be
+            // inline comment content or YAML expands `key: null` into a nested null value.
+            const comments = [];
+            if ("commentBefore" in existing && typeof existing.commentBefore === "string") {
+                comments.push(existing.commentBefore);
+            }
+            if ("comment" in existing && typeof existing.comment === "string") {
+                comments.push(existing.comment);
             }
+            if (comments.length)
+                tombstone.comment = comments.join("\n");
         }
+        doc.setIn(path, tombstone);
+        return;
     }
-    for (const [key, dest] of [["adapters", out.denyAdapters], ["models", out.denyModels]]) {
-        const seq = doc.getIn(["routing", "deny", key]);
-        if (!isSeq(seq))
+    if (!isSeq(existing)) {
+        doc.setIn(path, doc.createNode(values));
+        return;
+    }
+    const available = [...existing.items];
+    existing.items = values.map((value) => {
+        const at = available.findIndex((item) => isScalar(item) && String(item.value) === value);
+        if (at >= 0)
+            return available.splice(at, 1)[0];
+        return doc.createNode(value);
+    });
+}
+function deleteEmptyMap(doc, path) {
+    const node = doc.getIn(path, true);
+    if (isMap(node) && node.items.length === 0)
+        doc.deleteIn(path);
+}
+/** 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 function renderFleetOverlayWrite(priorBytes, write) {
+    const doc = parseDocument(priorBytes);
+    if (doc.errors.length)
+        throw doc.errors[0];
+    const { initial, edited } = write;
+    const denyChanged = sortedUnique(initial.denyAdapters).join() !== sortedUnique(edited.denyAdapters).join()
+        || sortedUnique(initial.denyModels).join() !== sortedUnique(edited.denyModels).join();
+    if (denyChanged) {
+        setStringSequencePreservingComments(doc, ["routing", "deny", "adapters"], edited.denyAdapters.length ? sortedUnique(edited.denyAdapters) : null);
+        setStringSequencePreservingComments(doc, ["routing", "deny", "models"], edited.denyModels.length ? sortedUnique(edited.denyModels) : null);
+    }
+    for (const shape of new Set([...Object.keys(initial.map), ...Object.keys(edited.map)])) {
+        const before = initial.map[shape];
+        const after = edited.map[shape];
+        if (JSON.stringify(before?.pin) !== JSON.stringify(after?.pin)) {
+            if (after?.pin === undefined)
+                doc.deleteIn(["routing", "map", shape, "pin"]);
+            else
+                doc.setIn(["routing", "map", shape, "pin"], doc.createNode(after.pin));
+        }
+        if (JSON.stringify(before?.prefer) !== JSON.stringify(after?.prefer)) {
+            // Clearing a resolved list must mask the lower layer with [], not delete the key and inherit it again.
+            setStringSequencePreservingComments(doc, ["routing", "map", shape, "prefer"], after?.prefer ?? []);
+        }
+        if (before?.escalate !== after?.escalate) {
+            if (after?.escalate === undefined)
+                doc.deleteIn(["routing", "map", shape, "escalate"]);
+            else
+                setScalarPreservingComment(doc, ["routing", "map", shape, "escalate"], after.escalate);
+        }
+    }
+    for (const shape of new Set([...Object.keys(initial.floors), ...Object.keys(edited.floors)])) {
+        if (initial.floors[shape] === edited.floors[shape])
             continue;
-        for (const item of seq.items) {
-            const n = note(item);
-            if (isScalar(item) && n)
-                dest[String(item.value)] = n;
+        const tier = edited.floors[shape];
+        if (tier === undefined)
+            doc.deleteIn(["routing", "floors", shape]);
+        else
+            setScalarPreservingComment(doc, ["routing", "floors", shape], tier);
+    }
+    for (const adapter of new Set([...Object.keys(initial.tiers), ...Object.keys(edited.tiers)])) {
+        const beforeModels = initial.tiers[adapter] ?? {};
+        const afterModels = edited.tiers[adapter] ?? {};
+        let firstTouch;
+        for (const model of new Set([...Object.keys(beforeModels), ...Object.keys(afterModels)])) {
+            const before = beforeModels[model];
+            const after = afterModels[model];
+            if (JSON.stringify(before) === JSON.stringify(after) || after === null || after === undefined)
+                continue;
+            firstTouch ??= unpackFleetProvenance(after.provenance).firstTouch;
+        }
+        const ft = firstTouch;
+        if (ft) {
+            if (doc.getIn(["tiers", adapter, "vendor"]) === undefined) {
+                setScalarPreservingComment(doc, ["tiers", adapter, "vendor"], ft.vendor);
+            }
+            if (doc.getIn(["tiers", adapter, "channel"]) === undefined) {
+                setScalarPreservingComment(doc, ["tiers", adapter, "channel"], ft.channel);
+            }
+        }
+        for (const model of new Set([...Object.keys(beforeModels), ...Object.keys(afterModels)])) {
+            const before = beforeModels[model];
+            const after = afterModels[model];
+            if (JSON.stringify(before) === JSON.stringify(after))
+                continue;
+            const path = ["tiers", adapter, "models", model];
+            if (after === null || after === undefined)
+                setScalarPreservingComment(doc, path, null);
+            else
+                setScalarPreservingComment(doc, path, after.tier, unpackFleetProvenance(after.provenance).provenance);
         }
     }
-    return out;
+    if (write.mode !== undefined) {
+        setScalarPreservingComment(doc, ["routing", "mode"], write.mode);
+    }
+    if (write.steering) {
+        for (const key of ["review", "consult"]) {
+            const before = write.steering.initial[key];
+            const after = write.steering.edited[key];
+            if (JSON.stringify(before) === JSON.stringify(after))
+                continue;
+            if (after === undefined) {
+                doc.deleteIn([key, "prefer"]);
+                deleteEmptyMap(doc, [key]);
+            }
+            else {
+                setStringSequencePreservingComments(doc, [key, "prefer"], after);
+            }
+        }
+    }
+    // Fleet's established note style uses two spaces before `#`; the Document remains the sole
+    // comment writer while preserving that byte-level convention for old and newly-authored notes.
+    return doc.toString({
+        commentString: (comment) => comment.replace(/^(?!$)(?: $)?/gm, " #"),
+    });
 }
 /** Build the repo overlay fragment fleet would write for edits since session start. */
-export function fleetRepoOverlayFromDelta(initial, edited, existingRepo = {}) {
+export function fleetRepoOverlayFromDelta(initial, edited, existingRepo = {}, firstTouches = {}) {
     if (fleetEditableEquals(initial, edited))
         return {};
     const out = structuredClone(existingRepo);
@@ -74,8 +209,13 @@ export function fleetRepoOverlayFromDelta(initial, edited, existingRepo = {}) {
     }
     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 (JSON.stringify(initial.map[shape]) !== JSON.stringify(edited.map[shape])) {
+            const next = { ...edited.map[shape] };
+            if (initial.map[shape]?.prefer !== undefined && edited.map[shape]?.prefer === undefined) {
+                next.prefer = [];
+            }
+            mapDelta[shape] = next;
+        }
     }
     if (Object.keys(mapDelta).length) {
         routing.map = { ...routing.map, ...mapDelta };
@@ -111,9 +251,17 @@ export function fleetRepoOverlayFromDelta(initial, edited, existingRepo = {}) {
             }
         }
         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 } };
+            const existingEntry = tiersOut[adapter] ?? {};
+            const firstTouch = firstTouches[adapter];
+            // Spread the whole entry rather than a known-key projection: vendor/channel/windows and sibling
+            // keys introduced by newer schemas all survive. A genuinely new entry receives only facts the
+            // adapter/operator declared; channel is never inferred from the binary.
+            tiersOut[adapter] = {
+                ...existingEntry,
+                ...(existingEntry.vendor === undefined && firstTouch ? { vendor: firstTouch.vendor } : {}),
+                ...(existingEntry.channel === undefined && firstTouch ? { channel: firstTouch.channel } : {}),
+                models: { ...existingEntry.models, ...modelDelta },
+            };
             tiersTouched = true;
         }
     }
@@ -121,11 +269,11 @@ export function fleetRepoOverlayFromDelta(initial, edited, existingRepo = {}) {
         out.tiers = tiersOut;
     return out;
 }
-export function repoOverlayYaml(overlay, provenance = {}, denyNotes = {}) {
+export function repoOverlayYaml(overlay) {
     if (!Object.keys(overlay).length)
         return "";
     const fleet = fleetSubset(overlay);
-    const fleetBody = serializeFleetOverlay(fleet, provenance, denyNotes);
+    const fleetBody = serializeFleetOverlay(fleet);
     const rest = { ...overlay };
     for (const k of FLEET_OVERLAY_KEYS)
         delete rest[k];
@@ -134,7 +282,7 @@ export function repoOverlayYaml(overlay, provenance = {}, denyNotes = {}) {
     const head = stringify(rest).trimEnd();
     return fleetBody ? `${head}\n${fleetBody}` : `${head}\n`;
 }
-export function serializeFleetOverlay(overlay, provenance = {}, denyNotes = {}) {
+export function serializeFleetOverlay(overlay) {
     if (!Object.keys(overlay).length)
         return "";
     const lines = [];
@@ -142,8 +290,6 @@ export function serializeFleetOverlay(overlay, provenance = {}, denyNotes = {})
     // 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 [];
@@ -152,9 +298,6 @@ export function serializeFleetOverlay(overlay, provenance = {}, denyNotes = {})
         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;
@@ -177,32 +320,7 @@ export function serializeFleetOverlay(overlay, provenance = {}, denyNotes = {})
     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}: {}`);
+            lines.push(...block({ [adapter]: entry }, "  "));
         }
     }
     return `${lines.join("\n")}\n`;

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

@@ -0,0 +1,23 @@
+export type FleetWhySource = "repo-overlay" | "global-config" | "seed-default" | "operator-pinned" | "defaulted";
+export type FleetWhyValue<Id extends string = string> = {
+    id: Id;
+    effective: string;
+    /** Dotted config path whose winning declaration produced this value. */
+    declaredAt?: string;
+    /** A live Shapes-screen pin outranks every persisted declaration. */
+    operatorPinned?: boolean;
+    /** Paste-ready only: projection and renderers never execute setup actions. */
+    setupCommand?: string;
+};
+export type FleetWhyRow<Id extends string = string> = FleetWhyValue<Id> & {
+    source: FleetWhySource;
+    label: string;
+};
+export type FleetWhyOptions = {
+    repoRoot: string;
+    globalDir?: string;
+};
+/** The single fleet projection: every consumer receives the same value/source/setup label. */
+export declare function projectFleetWhy<Id extends string>(values: readonly FleetWhyValue<Id>[], options: FleetWhyOptions): FleetWhyRow<Id>[];
+/** Plain line-mode twin of the Shapes rows; labels are projected, never reconstructed here. */
+export declare function renderFleetWhy(rows: readonly FleetWhyRow[]): string;

package/dist/config/fleet-why.js

@@ -0,0 +1,42 @@
+import { DEFAULT_CONFIG, fleetKeyLayer } from "./config.js";
+function valueAt(root, dotted) {
+    let value = root;
+    for (const part of dotted.split(".")) {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            return undefined;
+        value = value[part];
+    }
+    return value;
+}
+function sourceOf(value, options) {
+    if (value.operatorPinned)
+        return "operator-pinned";
+    if (!value.declaredAt)
+        return "defaulted";
+    const layer = fleetKeyLayer(options.repoRoot, value.declaredAt, {
+        globalDir: options.globalDir,
+    });
+    if (layer === "repo")
+        return "repo-overlay";
+    if (layer === "global")
+        return "global-config";
+    return valueAt(DEFAULT_CONFIG, value.declaredAt) === undefined
+        ? "defaulted"
+        : "seed-default";
+}
+/** The single fleet projection: every consumer receives the same value/source/setup label. */
+export function projectFleetWhy(values, options) {
+    return values.map((value) => {
+        const source = sourceOf(value, options);
+        const setup = value.setupCommand ? `\n    setup: ${value.setupCommand}` : "";
+        return {
+            ...value,
+            source,
+            label: `${value.id}  →  ${value.effective}  · source: ${source}${setup}`,
+        };
+    });
+}
+/** Plain line-mode twin of the Shapes rows; labels are projected, never reconstructed here. */
+export function renderFleetWhy(rows) {
+    return ["tickmarkr fleet --why — effective shape routing", ...rows.map((row) => row.label)].join("\n");
+}

package/dist/drivers/herdr.d.ts

@@ -2,6 +2,7 @@ import { type ExecutorDriver, type NotifyOpts, type Slot, type SlotOpts } from "
 export declare const TRAILER_SAFE_FLOOR_COLS = 108;
 export declare const TRAILER_WIDTH_MARGIN = 2;
 export declare const DELIVERY_ATTEMPTS = 3;
+export declare const DISPATCH_START_PREFIX = "TICKMARKR_START_";
 export interface HerdrTimeSource {
     now: () => number;
     sleep: (ms: number) => Promise<void>;
@@ -12,12 +13,21 @@ export declare class DeliveryReadinessError extends Error {
     readonly phase = "READINESS";
     constructor(waitedMs: number, transcript: string);
 }
+export declare class DeliveryCorruptedError extends Error {
+    readonly pane: string;
+    readonly transcript: string;
+    readonly phase = "DISPATCH";
+    constructor(pane: string, reason: string, transcript: string);
+}
+export type DriverJournal = (event: string, slotName: string, data: Record<string, unknown>) => void;
 /** First-generation join direction from measured trailer-safe floor (43-MEASUREMENT.md). */
 export declare function workerSplitDirection(paneCols: number | null, safeFloor?: number, margin?: number): "right" | "down";
+export declare function taskGroupOf(name: string): string | undefined;
 export declare class HerdrDriver implements ExecutorDriver {
     private bin;
     private workersPerTab;
     private time;
+    private journal?;
     id: string;
     interactive: boolean;
     private groups;
@@ -26,16 +36,18 @@ export declare class HerdrDriver implements ExecutorDriver {
     private dispatchLeases;
     private deliveredPanes;
     private inputBoxes;
+    private bootstraps;
+    private journalRoots;
     private ws;
     private callerPane;
     private watches;
-    constructor(bin?: string, workersPerTab?: number, time?: HerdrTimeSource);
+    constructor(bin?: string, workersPerTab?: number, time?: HerdrTimeSource, journal?: DriverJournal | undefined);
+    private appendDispatchRetry;
     private serial;
     private deliveryQueue;
     private reserveDispatch;
     private verifyPaneIdentityBinding;
     private deliveryMatches;
-    private shellExecutionEchoed;
     private submissionRegistered;
     static available(): boolean;
     private herdr;
@@ -52,7 +64,13 @@ export declare class HerdrDriver implements ExecutorDriver {
     private glyphFor;
     private joinGroup;
     run(slot: Slot, cmd: string): Promise<void>;
-    private deliver;
+    private dispatchWithRetry;
+    private isTuiTurn;
+    private dispatch;
+    private deliverAtomic;
+    private awaitDispatchAck;
+    private freshPane;
+    private deliverTyped;
     nudge(slot: Slot, message: string): Promise<boolean>;
     private deliverPersistentShellCommand;
     private submitVerifiedDelivery;