tickmarkr 1.55.0 → 1.56.0

package/README.md

@@ -143,11 +143,19 @@ away from a failing adapter will never retry it in subsequent `tickmarkr resume`
 
 ## Choosing your fleet: `tickmarkr fleet`
 
-`tickmarkr doctor` is a pure sensor; `tickmarkr fleet` is the actuator. It walks four screens —
-fleet overview, membership (allow/deny), model tiers, and per-shape routing — and ends in a
-unified diff of your config overlay that is written **only on explicit confirm**. Pressing Enter
-through every screen writes nothing. Assigning a tier to a model that has no classification yet
-requires a typed benchmark-provenance note, stored as a config comment beside the assignment.
+`tickmarkr doctor` is a pure sensor; `tickmarkr fleet` is the actuator. It walks six steps —
+probe data, agent CLIs, model tiers, routing mode, shape routing with a candidate picker, and
+steering preferences — and ends in a unified diff of your config overlay that is written **only
+on explicit confirm**. Pressing Enter through every step writes nothing. Assigning a tier to a
+model that has no classification yet requires a typed benchmark-provenance note, stored as a
+config comment beside the assignment.
+
+The shape routing step (step 5/6) features an **arrow-driven candidate picker** that ranks
+available channels by the production router's own logic, showing economics (tier + channel
+cost signals for API and sub channels) and the router's rationale for each rank. This replaces
+typed pin entry with verifiable suggestions. Step 4/6 shows an estimated spend context line
+across all shapes under each routing mode's resolved floors, also derived from the same preview
+routing machinery.
 
 ```bash
 tickmarkr fleet          # interactive editor (requires a TTY)

package/dist/cli/commands/fleet-picker.d.ts

@@ -0,0 +1,8 @@
+import type { Assignment, BillingChannel } from "../../adapters/types.js";
+import type { TickmarkrConfig } from "../../config/config.js";
+import type { Task } from "../../graph/schema.js";
+import { type RankedCandidate } from "../../route/candidates.js";
+import type { RoutingProfile } from "../../route/profile.js";
+export declare function costSignal(a: Assignment, pricing: Record<string, number>): string;
+export declare function candidateRow(c: RankedCandidate, pricing: Record<string, number>): string;
+export declare function shapeCandidates(task: Task, cfg: TickmarkrConfig, channels: BillingChannel[], profile?: RoutingProfile): RankedCandidate[];

package/dist/cli/commands/fleet-picker.js

@@ -0,0 +1,25 @@
+import { rankCandidates } from "../../route/candidates.js";
+// v1.56 T2: ranking glue + row presentation for the per-shape candidate picker. Everything here
+// is pure — the picker loop in fleet.ts mutates only in-memory editable state, and disk stays
+// reachable solely through fleet's diff-confirm + reload-guard write path.
+// Channel economics + tier, never invented dollars: a flat-rate sub quota rendered as $0 would be
+// the one dishonest thing this screen could say (v1.56 ruling — cost visible where the choice is made).
+export function costSignal(a, pricing) {
+    if (a.channel === "sub")
+        return "sub flat-rate quota";
+    const perTask = pricing[a.tier];
+    return perTask == null ? "api metered" : `api ~$${perTask.toFixed(2)}/task`;
+}
+export function candidateRow(c, pricing) {
+    const a = c.assignment;
+    const override = c.belowFloor ? "  · below floor — operator override" : "";
+    return `${a.adapter}:${a.model}  ${a.tier}  ${costSignal(a, pricing)}  — ${c.why}${override}`;
+}
+// Ranking ignores the shape's own map pin so a pinned shape still offers the full candidate
+// order — route() returns a map pin first and fail-louds on its exclusion, which would collapse
+// the picker to a single row. No hidden mutation: fresh cfg objects only.
+export function shapeCandidates(task, cfg, channels, profile) {
+    const { pin: _pin, ...entry } = cfg.routing.map[task.shape] ?? {};
+    const map = { ...cfg.routing.map, [task.shape]: entry };
+    return rankCandidates(task, { ...cfg, routing: { ...cfg.routing, map } }, channels, profile);
+}

package/dist/cli/commands/fleet.js

@@ -8,6 +8,7 @@ import { fleetUnclassifiedModels } from "../../adapters/model-lints.js";
 import { GLYPHS, bold, legend as legendText, toggleActive, toggleInactive } from "../../brand.js";
 import { fleetEditableFromConfig, fleetEditableEquals, fleetRepoOverlayFromDelta, formatFleetPrint, globalConfigDir, overlayBytesLoadError, overlayPreferShapes, readOverlayFile, repoOverlayPath, repoOverlayYaml, ROUTING_MODES, unifiedYamlDiff, } from "../../config/config.js";
 import { SHAPES, TIERS } from "../../graph/schema.js";
+import { candidateRow, costSignal, shapeCandidates } from "./fleet-picker.js";
 import { route } from "../../route/router.js";
 import { resolveRunMode } from "../../run/daemon.js";
 import { loadRoutingProfile } from "../../run/journal.js";
@@ -308,6 +309,46 @@ export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters(),
         // step 4/6 — routing mode (selection is in-memory; the write happens only through the diff confirm).
         // Candidate floor tables come from the ONE preset compiler via resolveRunMode — no mode math here.
         const modeCfgs = Object.fromEntries(ROUTING_MODES.map((m) => [m, m === rm.mode.mode ? rm : resolveRunMode(cwd, { flag: m, globalDir })]));
+        // v1.56 T3: both screens preview-route through ONE lens — the same live channel set, learned
+        // profile, and per-mode resolved floors — so the mode spend context and the shape rows can
+        // never disagree about what the router would do.
+        const channels = discoverChannels(cfg, adapters, health);
+        const profile = loadRoutingProfile(cwd, cfg, { preview: true });
+        const previewCfg = (m) => ({ ...cfg, routing: { ...cfg.routing, map: editable.map, floors: modeCfgs[m].cfg.routing.floors } });
+        // Estimated spend context under the highlighted mode: tier mix across all nine preview shapes,
+        // then channel economics — dollars only for api-routed shapes (plan.ts's rough per-task
+        // pricing table); a sub channel is flat-rate quota and never renders as a dollar amount.
+        const modeSpend = (cand) => {
+            const tierCount = {};
+            let subs = 0;
+            let apiN = 0;
+            let apiUsd = 0;
+            for (const shape of SHAPES) {
+                try {
+                    const a = route(previewTask(shape), previewCfg(cand), channels, profile).assignment;
+                    tierCount[a.tier] = (tierCount[a.tier] ?? 0) + 1;
+                    if (a.channel === "sub")
+                        subs += 1;
+                    else {
+                        apiN += 1;
+                        apiUsd += cfg.pricing[a.tier] ?? 0;
+                    }
+                }
+                catch {
+                    // unroutable under this mode's floors — the shape screen names the error per row
+                }
+            }
+            const mix = [...TIERS].reverse().flatMap((t) => (tierCount[t] ? [`${tierCount[t]} ${t}`] : [])).join(" · ");
+            const parts = [];
+            if (subs)
+                parts.push(`${subs === SHAPES.length ? "all" : subs} sub (flat-rate quota)`);
+            if (apiN)
+                parts.push(`${apiN} api · est. cost (API shapes only, rough): ~$${apiUsd.toFixed(2)}`);
+            const unroutable = SHAPES.length - subs - apiN;
+            if (unroutable)
+                parts.push(`${unroutable} unroutable`);
+            return `  mix: ${mix} — ${parts.join(" · ")}`;
+        };
         const modeRows = () => ROUTING_MODES.map((m) => `${m === rm.mode.mode ? toggleActive() : " "} ${m.padEnd(11)}  ${MODE_GLOSS[m]}`);
         // preview: the highlighted mode's resolved floor table diffed against the current mode
         const floorPreview = (cand) => {
@@ -325,7 +366,11 @@ export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters(),
         const modeLegend = "↑↓/jk move · enter select · esc/q quit";
         let modeCursor = ROUTING_MODES.indexOf(rm.mode.mode);
         let selectedMode = rm.mode.mode;
-        const modeFrame = () => [...listFrame(modeTitle, modeLegend, modeRows(), modeCursor), ...floorPreview(ROUTING_MODES[modeCursor])];
+        const modeFrame = () => [
+            ...listFrame(modeTitle, modeLegend, modeRows(), modeCursor),
+            modeSpend(ROUTING_MODES[modeCursor]),
+            ...floorPreview(ROUTING_MODES[modeCursor]),
+        ];
         term.frame(modeFrame());
         for (;;) {
             const k = await term.key();
@@ -341,17 +386,15 @@ export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters(),
                 term.frame(modeFrame());
             }
         }
-        // step 5/6 — shape routing (typed entry for pin/tier/prefer from the highlighted row);
+        // step 5/6 — shape routing (candidate picker for pin, typed entry for prefer);
         // previews route under the SELECTED mode's resolved floors, never a floor edit of its own
-        const channels = discoverChannels(cfg, adapters, health);
-        const profile = loadRoutingProfile(cwd, cfg, { preview: true });
         const autoPrefer = readAutoPrefer(cwd);
         const overlayShapes = overlayPreferShapes(cwd, { globalDir });
         const shapeRows = () => SHAPES.map((shape) => {
             let now;
             try {
-                const r = route(previewTask(shape), { ...cfg, routing: { ...cfg.routing, map: editable.map, floors: modeCfgs[selectedMode].cfg.routing.floors } }, channels, profile);
-                now = `${r.assignment.adapter}:${r.assignment.model} (${r.assignment.channel}, ${r.assignment.tier})`;
+                const r = route(previewTask(shape), previewCfg(selectedMode), channels, profile);
+                now = `${r.assignment.adapter}:${r.assignment.model} (${r.assignment.channel}, ${r.assignment.tier})  ${costSignal(r.assignment, cfg.pricing)}`;
             }
             catch (e) {
                 now = e.message;
@@ -385,12 +428,33 @@ export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters(),
                 changed = true;
             }
             else if (k.name === "p") {
-                const pin = await term.askTyped("pin adapter:model> ");
-                const i = pin.indexOf(":");
-                if (i < 1)
-                    return { out: "fleet: pin must be adapter:model", code: 1 };
-                editable.map[shape] = { pin: { via: pin.slice(0, i), model: pin.slice(i + 1) } };
-                changed = true;
+                // v1.56 T2: arrow-driven candidate picker replaces the typed pin entry (operator ruling:
+                // the suggestion proposes, the user disposes). Every rank is a production route() result
+                // (T1 seam); a pick mutates editable only — the write still funnels through the ONE
+                // diff-confirm + reload-guard path below. The picker adds no listeners of its own, so
+                // every exit path inherits term.close()'s release-and-pause contract in the finally.
+                const cand = shapeCandidates(previewTask(shape), previewCfg(selectedMode), channels, profile);
+                let pCursor = 0;
+                const pickerFrame = () => listFrame(`pick · ${shape}`, "↑↓/jk move · enter pin · esc cancel · q quit", cand.map((c) => candidateRow(c, cfg.pricing)), pCursor);
+                term.frame(pickerFrame());
+                for (;;) {
+                    const pk = await term.key();
+                    if (pk.name === "q" || (pk.ctrl === true && pk.name === "c"))
+                        return QUIT;
+                    if (pk.name === "escape")
+                        break;
+                    if (isNext(pk) && cand.length > 0) {
+                        const a = cand[pCursor].assignment;
+                        editable.map[shape] = { pin: { via: a.adapter, model: a.model } };
+                        break;
+                    }
+                    const pMoved = moveCursor(pk, pCursor, cand.length);
+                    if (pMoved !== pCursor) {
+                        pCursor = pMoved;
+                        term.frame(pickerFrame());
+                    }
+                }
+                changed = true; // the picker replaced the frame — every exit redraws the shape screen
             }
             else if (k.name === "f") {
                 const pref = await term.askTyped("prefer (comma-separated adapters or adapter:model)> ");

package/dist/route/candidates.d.ts

@@ -0,0 +1,11 @@
+import { type Assignment, type BillingChannel } from "../adapters/types.js";
+import type { TickmarkrConfig } from "../config/config.js";
+import type { Task } from "../graph/schema.js";
+import type { RoutingProfile } from "./profile.js";
+import { type RoutingPreferContext } from "./router.js";
+export interface RankedCandidate {
+    assignment: Assignment;
+    why: string;
+    belowFloor: boolean;
+}
+export declare function rankCandidates(task: Task, cfg: TickmarkrConfig, channels: BillingChannel[], profile?: RoutingProfile, preferCtx?: RoutingPreferContext): RankedCandidate[];

package/dist/route/candidates.js

@@ -0,0 +1,35 @@
+import { channelKey } from "../adapters/types.js";
+import { route, RoutingError } from "./router.js";
+// v1.56 T1 (scoper ruling 2, RULED FOR FABLE): NO comparator lives here — every rank IS a
+// production route() result. Order derives solely from re-calling route with a growing exclusion
+// set (the OBS-57 exclude seam), exploration off so repeated calls agree. When the eligible pool
+// exhausts (RoutingError), the advisory floor for this shape is dropped ONCE and the remaining
+// live channels rank after, marked belowFloor — mirroring the routes-but-lints semantics a
+// below-floor map pin already has (router.ts pin path).
+export function rankCandidates(task, cfg, channels, profile, preferCtx) {
+    const ranked = [];
+    const exclude = new Set();
+    let effCfg = cfg;
+    let belowFloor = false;
+    while (exclude.size < channels.length) {
+        let r;
+        try {
+            r = route(task, effCfg, channels, profile, preferCtx, exclude, { noExplore: true });
+        }
+        catch (e) {
+            if (!(e instanceof RoutingError))
+                throw e;
+            if (belowFloor)
+                break; // pool exhausted (or an unresolvable map pin) — ranking is complete
+            // eligible pool dry: drop this shape's advisory floor and keep iterating the production
+            // router over the leftover live channels. No hidden mutation — fresh cfg objects only.
+            belowFloor = true;
+            const { [task.shape]: _dropped, ...floors } = cfg.routing.floors;
+            effCfg = { ...cfg, routing: { ...cfg.routing, floors } };
+            continue;
+        }
+        ranked.push({ assignment: r.assignment, why: r.provenance, belowFloor });
+        exclude.add(channelKey(r.assignment));
+    }
+    return ranked;
+}

package/package.json

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