tickmarkr 1.45.0 → 1.47.0

package/dist/adapters/fake.js

@@ -37,7 +37,7 @@ export class FakeAdapter {
         let isJudge = false;
         try {
             prompt = readFileSync(promptFile, "utf8");
-            isJudge = /TICKMARKR-JUDGE/.test(prompt);
+            isJudge = /TICKMARKR-(?:JUDGE|SCOPE)/.test(prompt);
         }
         catch {
             // unreadable promptFile: can't detect role; serve static values (legacy headless-call behavior)
@@ -61,7 +61,7 @@ export class FakeAdapter {
             writeFileSync(p, JSON.stringify(val ?? {}, null, 1));
             return p;
         };
-        return `bash -c 'grep -q TICKMARKR-JUDGE ${shq(promptFile)} && cat ${shq(serve("judge"))}; grep -q TICKMARKR-REVIEW ${shq(promptFile)} && cat ${shq(serve("review"))}; grep -q TICKMARKR-CONSULT ${shq(promptFile)} && cat ${shq(serve("consult"))}; true'`;
+        return `bash -c 'grep -Eq "TICKMARKR-(JUDGE|SCOPE)" ${shq(promptFile)} && cat ${shq(serve("judge"))}; grep -q TICKMARKR-REVIEW ${shq(promptFile)} && cat ${shq(serve("review"))}; grep -q TICKMARKR-CONSULT ${shq(promptFile)} && cat ${shq(serve("consult"))}; true'`;
     }
     resumeCommand(_sessionId, promptFile, model) {
         return this.interactiveCommand(promptFile, model) ?? this.headlessCommand(promptFile, model);

package/dist/adapters/model-lints.d.ts

@@ -1,8 +1,21 @@
 import { type TickmarkrConfig } from "../config/config.js";
+import type { Task } from "../graph/schema.js";
 import { type AuthHealth, type WorkerAdapter } from "./types.js";
 export declare const SEED_STAMPED = "2026-07-09";
 export declare const MODEL_STALE_DAYS = 30;
 export declare const ttyVisual: () => boolean;
+/** True when any tier entry declares at least one model window. */
+export declare function hasWindowsConfig(cfg: TickmarkrConfig): boolean;
+export declare function declaredModelWindow(cfg: TickmarkrConfig, adapter: string, model: string): number | undefined;
+/** Best-effort plan-time payload estimate: prompt shell + context + files[] byte sizes. */
+export declare function estimateTaskPayloadTokens(task: Task, repoRoot: string, feedback?: string): number;
+export type RoutedAssignment = {
+    taskId: string;
+    adapter: string;
+    model: string;
+};
+/** Advisory only — absent windows config or undeclared model window ⇒ no lint. */
+export declare function contextWindowLints(tasks: ReadonlyArray<Task>, assignments: ReadonlyArray<RoutedAssignment>, cfg: TickmarkrConfig, repoRoot: string): string[];
 export declare function seedPreferLints(cfg: TickmarkrConfig, health: Record<string, AuthHealth>, adapters: WorkerAdapter[], overlayPreferShapes?: ReadonlySet<string>): string[];
 export declare function modelLints(cfg: TickmarkrConfig, health: Record<string, AuthHealth>, adapters: WorkerAdapter[], opts?: {
     tty?: boolean;
@@ -15,3 +28,9 @@ export declare function formatModelAuthLine(excluded: {
     probedAt: string;
 }[], tty?: boolean, stateDir?: string): string;
 export declare function suggestOverlay(cfg: TickmarkrConfig, health: Record<string, AuthHealth>, adapters: WorkerAdapter[], stateDir?: string): string;
+/** Unclassified models surfaced for fleet screen 2 (doctor matrix math, no tier fabrication). */
+export declare function fleetUnclassifiedModels(cfg: TickmarkrConfig, health: Record<string, AuthHealth>, adapters: WorkerAdapter[]): {
+    adapter: string;
+    model: string;
+    detectedAt?: string;
+}[];

package/dist/adapters/model-lints.js

@@ -1,6 +1,8 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
 import { DEFAULT_CONFIG, TIER_RANK } from "../config/config.js";
+import { buildTaskPrompt } from "./prompt.js";
 import { MODEL_ID_RE } from "./types.js";
-// date the tiers seeds were last live-verified (Phase 6/7 reseed) — surfaced when an adapter has no list surface.
 export const SEED_STAMPED = "2026-07-09";
 // knowledge past this age gets a "rerun tickmarkr doctor" nudge (BLOCKED_POLL_MS-style named constant).
 export const MODEL_STALE_DAYS = 30;
@@ -14,6 +16,57 @@ const TTY_LINT_CAP = 3;
 const DEFAULT_STATE_DIR = ".tickmarkr";
 const doctorJsonRef = (stateDir) => ` — see ${stateDir}/doctor.json`;
 export const ttyVisual = () => process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
+// ponytail: chars/4 token heuristic — good enough for advisory plan lint; no tokenizer dep.
+const CHARS_PER_TOKEN = 4;
+/** True when any tier entry declares at least one model window. */
+export function hasWindowsConfig(cfg) {
+    return Object.values(cfg.tiers).some((t) => t.windows && Object.keys(t.windows).length > 0);
+}
+export function declaredModelWindow(cfg, adapter, model) {
+    return cfg.tiers[adapter]?.windows?.[model];
+}
+function fileBytes(repoRoot, rel) {
+    if (rel.includes("*") || rel.includes("?") || rel.includes("{"))
+        return 0; // glob — not measurable at plan time
+    try {
+        const p = join(repoRoot, rel);
+        if (!existsSync(p))
+            return 0;
+        return statSync(p).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Best-effort plan-time payload estimate: prompt shell + context + files[] byte sizes. */
+export function estimateTaskPayloadTokens(task, repoRoot, feedback = "") {
+    let bytes = buildTaskPrompt(task, feedback).length;
+    for (const p of task.context)
+        bytes += fileBytes(repoRoot, p);
+    for (const p of task.files)
+        bytes += fileBytes(repoRoot, p);
+    return Math.ceil(bytes / CHARS_PER_TOKEN);
+}
+/** Advisory only — absent windows config or undeclared model window ⇒ no lint. */
+export function contextWindowLints(tasks, assignments, cfg, repoRoot) {
+    if (!hasWindowsConfig(cfg))
+        return [];
+    const byId = new Map(assignments.map((a) => [a.taskId, a]));
+    const lints = [];
+    for (const t of tasks) {
+        const a = byId.get(t.id);
+        if (!a)
+            continue;
+        const window = declaredModelWindow(cfg, a.adapter, a.model);
+        if (window === undefined)
+            continue;
+        const est = estimateTaskPayloadTokens(t, repoRoot);
+        if (est > window) {
+            lints.push(`${t.id}: payload ~${est} tokens exceeds ${a.adapter}:${a.model} window ${window}`);
+        }
+    }
+    return lints;
+}
 const adapterHasAuthedChannel = (adapterId, shape, cfg, health, adapters) => {
     const entry = cfg.routing.map[shape];
     const minTier = entry?.tier ?? cfg.routing.floors[shape] ?? "cheap";
@@ -175,3 +228,23 @@ function referenceWarning(cfg, adapterId, model) {
         refs.push("consult");
     return refs.length ? `  # WARNING: still referenced by ${refs.join(", ")} — remap before removing` : "";
 }
+/** Unclassified models surfaced for fleet screen 2 (doctor matrix math, no tier fabrication). */
+export function fleetUnclassifiedModels(cfg, health, adapters) {
+    const out = [];
+    for (const id of Object.keys(cfg.tiers)) {
+        if (!adapters.some((a) => a.id === id))
+            continue;
+        const h = health[id];
+        const detected = h?.models ?? [];
+        if (!detected.length)
+            continue;
+        const configured = new Set(Object.keys(cfg.tiers[id].models));
+        const date = h?.modelsDetectedAt?.split("T")[0];
+        for (const model of detected) {
+            if (configured.has(model) || LINT_VARIANT_RE.test(model))
+                continue;
+            out.push({ adapter: id, model, detectedAt: date });
+        }
+    }
+    return out;
+}

package/dist/adapters/registry.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { overlayPreferShapes, TIER_RANK } from "../config/config.js";
@@ -178,7 +178,13 @@ async function mapLimit(items, limit, fn) {
 }
 const doctorPath = (repoRoot) => join(repoRoot, stateDirName(repoRoot), "doctor.json");
 function readDoctorFile(repoRoot) {
-    return existsSync(doctorPath(repoRoot)) ? JSON.parse(readFileSync(doctorPath(repoRoot), "utf8")) : null;
+    try {
+        return existsSync(doctorPath(repoRoot)) ? JSON.parse(readFileSync(doctorPath(repoRoot), "utf8")) : null;
+    }
+    catch {
+        // A torn cache is disposable: callers already re-probe when this returns null.
+        return null;
+    }
 }
 export function writeDoctor(repoRoot, health) {
     tickmarkrDir(repoRoot);
@@ -187,7 +193,10 @@ export function writeDoctor(repoRoot, health) {
     delete payload[pendingAutoPreferKey];
     if (pending)
         payload.autoPrefer = pending;
-    writeFileSync(doctorPath(repoRoot), JSON.stringify(payload, null, 2) + "\n");
+    const path = doctorPath(repoRoot);
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(payload, null, 2) + "\n");
+    renameSync(tmp, path);
 }
 export function readDoctor(repoRoot) {
     const raw = readDoctorFile(repoRoot);

package/dist/brand.js

@@ -1,3 +1,4 @@
+import { shq } from "./adapters/types.js";
 // TTY-only pixel-tick logo (assets/mark.svg is the image twin — same block geometry).
 // Never printed to pipes — the non-TTY stdout surface is byte-pinned by tests and consumed by machines.
 const B = "\x1b[1m", R = "\x1b[0m";
@@ -26,5 +27,5 @@ export function paneDispatchScript(body) {
 }
 /** OBS-50: one short herdr pane-run line; bootstrap lives in the script file beside the prompt. */
 export function paneDispatchCommand(scriptPath) {
-    return `bash ${JSON.stringify(scriptPath)}`;
+    return `bash ${shq(scriptPath)}`;
 }

package/dist/cli/commands/approve.js

@@ -6,10 +6,10 @@ import { ATTEMPT_CAP_RELEASE, Journal } from "../../run/journal.js";
 // append-only journal. Writing it into tickmarkr's compiled graph artifact would be silently erased by
 // the next recompile (which re-emits humanGate:true from the plan frontmatter) — Phase 42 D-02.
 //
-// v1.24 OBS-18: when the park was attempt-cap (not a humanGate pre-dispatch park), the event also
-// carries `release: "attempt-cap"`. replayResumeState zeros the attempt budget on that marker so
-// resume dispatches instead of re-parking in the same tick; tried-list is preserved. humanGate
-// parks (attempts 0, reason starts with "humanGate:") stamp no release — byte-identical to GATE-08.
+// v1.24 OBS-18: when the park kind is attempt-cap (not a humanGate pre-dispatch park), the event
+// also carries `release: "attempt-cap"`. replayResumeState zeros the attempt budget on that marker so
+// resume dispatches instead of re-parking in the same tick; tried-list is preserved. Unknown kinds
+// receive no release and remain fail-closed to a human rather than being inferred from prose.
 //
 // Fail-closed (D-05): unknown runId, unknown taskId, a not-parked task, and a double-approve are all
 // LOUD refusals that name the reason and append NO event — never a silent no-op. A handler throw
@@ -30,10 +30,9 @@ export async function approve(argv, cwd = process.cwd()) {
         throw new Error(`task ${taskId} is ${status}, not a parked human gate — refusing (a silent no-op would be worse)`);
     }
     // OBS-18: only the most recent task-human for this task decides whether this approval grants a
-    // fresh attempt budget. Match the daemon's park reason literally (`attempt cap (N) reached`).
+    // fresh attempt budget. The closed daemon-issued kind, never a human prose string, controls release.
     const lastHuman = journal.read().filter((e) => e.event === "task-human" && e.taskId === taskId).at(-1);
-    const capPark = typeof lastHuman?.data.reason === "string"
-        && /attempt cap \(\d+\) reached/.test(lastHuman.data.reason);
+    const capPark = lastHuman?.data.kind === ATTEMPT_CAP_RELEASE;
     journal.append("task-approved", taskId, {
         by,
         ...(reason ? { reason } : {}),

package/dist/cli/commands/doctor.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { allAdapters, probeAll, probeModels, readAutoPrefer, servableExclusions, servabilityLine, writeDoctor } from "../../adapters/registry.js";
 import { BANNER } from "../../brand.js";
 import { tickmarkrDir, stateDirName } from "../../graph/graph.js";
-import { modelLints, suggestOverlay, ttyVisual } from "../../adapters/model-lints.js";
+import { declaredModelWindow, hasWindowsConfig, modelLints, suggestOverlay, ttyVisual } from "../../adapters/model-lints.js";
 import { DEFAULT_CONFIG, loadConfig, overlayPreferShapes } from "../../config/config.js";
 import { HerdrDriver } from "../../drivers/herdr.js";
 import { disallowedBy, excludedChannels, exclusionLine, preferRanks } from "../../route/preference.js";
@@ -121,6 +121,7 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
     // per adapter — they aren't routable, so they don't earn table rows.
     const trunc = (s, n) => (s.length <= n ? s : `${s.slice(0, n - 1)}…`);
     const dateOf = (iso) => iso.slice(0, 10);
+    const showWindows = hasWindowsConfig(cfg);
     const modelStatus = adapters.flatMap((a) => {
         const h = health[a.id];
         if (!h?.installed)
@@ -138,7 +139,10 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
             const d = disallowedBy({ adapter: a.id, model: m }, cfg.routing);
             const denied = d?.by === "deny" ? d.entry : "—";
             const pref = preferRanks({ adapter: a.id, model: m }, cfg).map((p) => `${p.shape}#${p.rank}`).join(",") || "—";
-            rows.push(`    ${m.padEnd(w)} ${classified[m].padEnd(8)} ${auth}  denied=${denied}  prefer=${pref}`);
+            const windowCol = showWindows
+                ? ` ${String(declaredModelWindow(cfg, a.id, m) ?? "—").padEnd(8)}`
+                : "";
+            rows.push(`    ${m.padEnd(w)} ${classified[m].padEnd(8)}${windowCol} ${auth}  denied=${denied}  prefer=${pref}`);
         }
         if (unclassified.length)
             rows.push(`    (${unclassified.length} more listed, unclassified)`);

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

@@ -0,0 +1,5 @@
+import type { WorkerAdapter } from "../../adapters/types.js";
+export declare function fleet(argv: string[], cwd?: string, adapters?: WorkerAdapter[]): Promise<string | {
+    out: string;
+    code: number;
+}>;

package/dist/cli/commands/fleet.js

@@ -0,0 +1,249 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+import { allAdapters, discoverChannels, doctorAgeMs, initDoctorReuse, readAutoPrefer } from "../../adapters/registry.js";
+import { fleetUnclassifiedModels } from "../../adapters/model-lints.js";
+import { fleetEditableFromConfig, fleetEditableEquals, fleetRepoOverlayFromDelta, formatFleetPrint, globalConfigDir, loadConfig, overlayPreferShapes, readOverlayFile, repoOverlayPath, repoOverlayYaml, unifiedYamlDiff, } from "../../config/config.js";
+import { SHAPES, TIERS } from "../../graph/schema.js";
+import { route } from "../../route/router.js";
+import { loadRoutingProfile } from "../../run/journal.js";
+const NON_TTY_MSG = "tickmarkr fleet: interactive fleet editor requires a TTY — use `tickmarkr fleet --print` for non-interactive output";
+const isDeniedAdapter = (id, editable) => editable.denyAdapters.includes(id);
+const isDeniedModel = (adapter, model, editable) => editable.denyModels.includes(`${adapter}:${model}`);
+function previewTask(shape) {
+    return {
+        id: "fleet-preview",
+        title: "fleet preview",
+        goal: "preview",
+        shape,
+        complexity: 3,
+        acceptance: ["done"],
+        deps: [],
+        files: [],
+        context: [],
+        gates: ["build", "test", "lint", "evidence", "scope", "acceptance", "review"],
+        humanGate: false,
+        status: "pending",
+        evidence: { commits: [], artifacts: [], gateResults: [] },
+    };
+}
+function formatAge(ageMs) {
+    if (ageMs === null)
+        return "no probe data";
+    const mins = Math.floor(ageMs / 60_000);
+    if (mins < 60)
+        return `${mins}m old`;
+    return `${Math.floor(mins / 60)}h old`;
+}
+function currentRepoOverlayText(repoRoot) {
+    const p = repoOverlayPath(repoRoot);
+    return existsSync(p) ? readFileSync(p, "utf8") : "";
+}
+function provenanceMap(editable) {
+    const out = {};
+    for (const [adapter, models] of Object.entries(editable.tiers)) {
+        for (const [model, v] of Object.entries(models)) {
+            if (v?.provenance) {
+                out[adapter] ??= {};
+                out[adapter][model] = v.provenance;
+            }
+        }
+    }
+    return out;
+}
+function proposedOverlayText(initial, editable, repoRoot) {
+    const merged = fleetRepoOverlayFromDelta(initial, editable, readOverlayFile(repoOverlayPath(repoRoot)));
+    return repoOverlayYaml(merged, provenanceMap(editable));
+}
+async function ask(rl, prompt) {
+    return (await rl.question(prompt)).trim();
+}
+export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters()) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            print: { type: "boolean" },
+            "global-dir": { type: "string" },
+            fresh: { type: "boolean" },
+        },
+    });
+    const globalDir = values["global-dir"] ?? globalConfigDir();
+    const print = values.print ?? false;
+    const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
+    if (print)
+        return formatFleetPrint(cwd, { globalDir });
+    if (!interactive)
+        return { out: NON_TTY_MSG, code: 1 };
+    const fresh = values.fresh ?? false;
+    const { reuse, health: cached } = initDoctorReuse(cwd, fresh);
+    if (!reuse || !cached) {
+        return {
+            out: "tickmarkr fleet: probe data missing or stale — run `tickmarkr doctor` first (fleet never re-probes; doctor is the sensor)",
+            code: 1,
+        };
+    }
+    const cfg = loadConfig(cwd, { globalDir });
+    const initial = fleetEditableFromConfig(cfg);
+    const editable = structuredClone(initial);
+    const health = cached;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        // screen 0 — sensor freshness
+        const ageLine = formatAge(doctorAgeMs(cwd));
+        let step = await ask(rl, `tickmarkr fleet — scope your fleet\n  probe data: ${ageLine} (.tickmarkr/doctor.json)\n  [Enter] use it   [r] refresh via doctor   [q] quit\n> `);
+        if (/^q$/i.test(step))
+            return "fleet: quit without writing";
+        if (/^r$/i.test(step)) {
+            return "fleet: run `tickmarkr doctor` to refresh probe data, then re-run `tickmarkr fleet` (doctor is the sensor; fleet never re-probes)";
+        }
+        // screen 1 — adapter membership (deny adapters)
+        const installed = adapters.filter((a) => health[a.id]?.installed);
+        const adapterLines = installed.map((a, i) => {
+            const h = health[a.id];
+            const on = !isDeniedAdapter(a.id, editable);
+            const mark = on ? "x" : " ";
+            const auth = h?.authed ? "authed" : "unauthed";
+            return `  ${i + 1}. [${mark}] ${a.id}  ${h?.version ?? "installed"}  ${auth}`;
+        });
+        step = await ask(rl, `screen 1/4 — agent CLIs  [number]=toggle  [Enter]=next\n${adapterLines.join("\n")}\n> `);
+        if (/^q$/i.test(step))
+            return "fleet: quit without writing";
+        if (step && step !== "") {
+            const n = Number.parseInt(step, 10);
+            if (Number.isInteger(n) && n >= 1 && n <= installed.length) {
+                const id = installed[n - 1].id;
+                const idx = editable.denyAdapters.indexOf(id);
+                if (idx === -1)
+                    editable.denyAdapters.push(id);
+                else
+                    editable.denyAdapters.splice(idx, 1);
+                editable.denyAdapters.sort();
+            }
+        }
+        // screen 2 — models per enabled adapter
+        const enabledAdapters = installed.filter((a) => !isDeniedAdapter(a.id, editable));
+        for (const a of enabledAdapters) {
+            const classified = editable.tiers[a.id] ?? {};
+            const models = Object.keys(classified);
+            const unclassified = fleetUnclassifiedModels(cfg, health, adapters).filter((u) => u.adapter === a.id);
+            const rows = [];
+            let row = 1;
+            const indexFor = new Map();
+            for (const m of models) {
+                const tier = classified[m];
+                const denied = isDeniedModel(a.id, m, editable) ? "deny" : "allow";
+                const mark = denied === "deny" ? " " : "x";
+                rows.push(`  ${row}. [${mark}] ${m}  ${tier?.tier ?? "???"}  ${denied === "deny" ? "denied" : "allowed"}`);
+                indexFor.set(String(row), { kind: "classified", model: m });
+                row++;
+            }
+            for (const u of unclassified) {
+                rows.push(`  ${row}. ( ) ${u.model}  ???  unclassified${u.detectedAt ? ` (${u.detectedAt})` : ""}`);
+                indexFor.set(String(row), { kind: "unclassified", model: u.model });
+                row++;
+            }
+            step = await ask(rl, `screen 2/4 — models · ${a.id}  [number]=toggle deny  [t <n> <tier>]=assign tier  [Enter]=next\n${rows.join("\n")}\n> `);
+            if (/^q$/i.test(step))
+                return "fleet: quit without writing";
+            if (step.startsWith("t ")) {
+                const [, numRaw, tierRaw] = step.split(/\s+/);
+                const tier = tierRaw;
+                if (!indexFor.has(numRaw) || !TIERS.includes(tier)) {
+                    return { out: "fleet: tier assignment requires a valid model number and tier (cheap|mid|frontier)", code: 1 };
+                }
+                const target = indexFor.get(numRaw);
+                if (target.kind !== "unclassified") {
+                    return { out: "fleet: tier reassignment on classified models is not supported in v1 — edit config directly", code: 1 };
+                }
+                const note = await ask(rl, "benchmark provenance note (required): ");
+                if (!note.trim())
+                    return { out: "fleet: assigning a tier to an unclassified model requires a typed benchmark-provenance note", code: 1 };
+                editable.tiers[a.id] ??= {};
+                editable.tiers[a.id][target.model] = { tier, provenance: note.trim() };
+            }
+            else if (step && /^\d+$/.test(step)) {
+                const target = indexFor.get(step);
+                if (target?.kind === "classified") {
+                    const key = `${a.id}:${target.model}`;
+                    const idx = editable.denyModels.indexOf(key);
+                    if (idx === -1)
+                        editable.denyModels.push(key);
+                    else
+                        editable.denyModels.splice(idx, 1);
+                    editable.denyModels.sort();
+                }
+            }
+        }
+        // screen 3 — per-shape routing
+        const channels = discoverChannels(cfg, adapters, health);
+        const profile = loadRoutingProfile(cwd, cfg, { preview: true });
+        const autoPrefer = readAutoPrefer(cwd);
+        const overlayShapes = overlayPreferShapes(cwd, { globalDir });
+        for (let si = 0; si < SHAPES.length; si++) {
+            const shape = SHAPES[si];
+            const entry = editable.map[shape] ?? {};
+            let now = "";
+            try {
+                const r = route(previewTask(shape), { ...cfg, routing: { ...cfg.routing, map: editable.map, floors: editable.floors } }, channels, profile);
+                now = `${r.provenance}\n       → ${r.assignment.adapter}:${r.assignment.model} (${r.assignment.channel}, ${r.assignment.tier})`;
+            }
+            catch (e) {
+                now = e.message;
+            }
+            const autoNote = autoPrefer?.[shape] && !overlayShapes.has(shape)
+                ? `\n  auto-prefer active — explicit prefer overrides it`
+                : "";
+            step = await ask(rl, `screen 3/4 — shape routing · ${shape} (${si + 1}/${SHAPES.length})\n  now: ${now}\n  [1] auto within tier  [2] pin channel  [3] edit tier  [4] edit prefer  [Enter]=keep${autoNote}\n> `);
+            if (/^q$/i.test(step))
+                return "fleet: quit without writing";
+            if (!step)
+                continue;
+            if (step === "1") {
+                const next = { ...entry };
+                delete next.pin;
+                editable.map[shape] = next;
+            }
+            else if (step === "2") {
+                const pin = await ask(rl, "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) } };
+            }
+            else if (step === "3") {
+                const tier = await ask(rl, `tier (${TIERS.join("|")})> `);
+                if (!TIERS.includes(tier))
+                    return { out: `fleet: invalid tier ${tier}`, code: 1 };
+                const next = { ...entry, tier };
+                delete next.pin;
+                editable.map[shape] = next;
+            }
+            else if (step === "4") {
+                const pref = await ask(rl, "prefer (comma-separated adapters or adapter:model)> ");
+                const prefer = pref.split(",").map((s) => s.trim()).filter(Boolean);
+                editable.map[shape] = { ...entry, prefer };
+            }
+        }
+        // review — unified diff + confirm
+        const before = currentRepoOverlayText(cwd);
+        const after = proposedOverlayText(initial, editable, cwd);
+        if (fleetEditableEquals(initial, editable) || before === after) {
+            return "fleet: no overlay changes (empty diff)";
+        }
+        const diff = unifiedYamlDiff(before, after, repoOverlayPath(cwd));
+        process.stdout.write(`\n${diff}\n`);
+        const confirm = await ask(rl, "write overlay? [y/N] ");
+        if (!/^y(?:es)?$/i.test(confirm))
+            return "fleet: discarded overlay changes";
+        const merged = fleetRepoOverlayFromDelta(initial, editable, readOverlayFile(repoOverlayPath(cwd)));
+        const body = repoOverlayYaml(merged, provenanceMap(editable));
+        const path = repoOverlayPath(cwd);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, body);
+        return `fleet: wrote ${path}`;
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/cli/commands/init.js

@@ -1,4 +1,4 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { parseArgs } from "node:util";
@@ -7,7 +7,59 @@ import { configTemplate, DEFAULT_CONFIG, globalConfigDir, loadConfig } from "../
 import { LEGACY_PREFIX, specTemplate } from "../../compile/native.js";
 import { BANNER } from "../../brand.js";
 import { tickmarkrDir } from "../../graph/graph.js";
+import { Journal } from "../../run/journal.js";
 import { doctor } from "./doctor.js";
+const SCAFFOLD_SPEC = "tickmarkr.spec.md";
+// Operator-approved (2026-07-17) environments footer — three rows; no npm install for herdr
+// (npm package "herdr" is a reserved 0.0.0 placeholder as of that date).
+const ENVIRONMENTS_FOOTER = [
+    "environments:",
+    "  herdr — the full cockpit — every worker, judge, and consult is a visible pane you can watch and unblock · https://herdr.dev",
+    "  claude code — tickmarkr init --agent installs the /tkr skills + AGENTS.md so Claude Code (or any agent CLI) drives the loop natively",
+    "  anywhere — no herdr? same fail-closed gates, headless subprocess driver",
+].join("\n");
+/** Latest journal without a run-end event, if any. */
+function activeRunId(cwd) {
+    const runId = Journal.latestRunId(cwd, { withJournal: true });
+    if (!runId)
+        return null;
+    try {
+        const events = Journal.open(cwd, runId).read();
+        if (events.some((e) => e.event === "run-end"))
+            return null;
+        return runId;
+    }
+    catch {
+        return null;
+    }
+}
+/** Relative paths of specs/*.spec.md already in the repo. */
+function existingSpecs(cwd) {
+    const dir = join(cwd, "specs");
+    if (!existsSync(dir))
+        return [];
+    try {
+        return readdirSync(dir)
+            .filter((f) => f.endsWith(".spec.md"))
+            .sort()
+            .map((f) => `specs/${f}`);
+    }
+    catch {
+        return [];
+    }
+}
+/** Context-aware next-steps line (operator-approved 2026-07-17). */
+function nextSteps(cwd, scaffoldedSpec) {
+    const runId = activeRunId(cwd);
+    if (runId)
+        return `run ${runId} active — tickmarkr status`;
+    const specs = existingSpecs(cwd);
+    if (specs.length > 0) {
+        const listed = specs.length <= 3 ? specs.join(", ") : `${specs.slice(0, 3).join(", ")}, …`;
+        return `next: existing specs under specs/ (${listed}) — tickmarkr compile <spec> && tickmarkr plan && tickmarkr run`;
+    }
+    return `next: edit ${scaffoldedSpec}, then tickmarkr compile ${scaffoldedSpec} && tickmarkr plan && tickmarkr run`;
+}
 const visual = () => process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
 const AGENT_SKILLS = ["tickmarkr-loop", "tickmarkr-auto"];
 const DOCS_BEGIN = "<!-- tickmarkr:agent-docs begin -->";
@@ -173,7 +225,7 @@ export async function init(argv, cwd = process.cwd()) {
     const repoConfigExists = existsSync(repoConfigPath);
     if (repoConfigExists)
         notes.push(`kept existing ${repoConfigPath}`);
-    const specPath = join(cwd, "tickmarkr.spec.md");
+    const specPath = join(cwd, SCAFFOLD_SPEC);
     if (existsSync(specPath)) {
         notes.push(`kept existing ${specPath}`);
     }
@@ -210,7 +262,7 @@ export async function init(argv, cwd = process.cwd()) {
     }
     if (values.agent)
         await installAgentFiles(cwd, values.force ?? false, values.docs ?? false, notes);
-    const body = `${notes.join("\n")}\n${doc}\nnext: edit tickmarkr.spec.md, then tickmarkr compile tickmarkr.spec.md && tickmarkr plan && tickmarkr run`;
+    const body = `${notes.join("\n")}\n${doc}\n${nextSteps(cwd, SCAFFOLD_SPEC)}\n${ENVIRONMENTS_FOOTER}`;
     if (visual() && !bannerEmitted)
         return BANNER + body;
     return body;

package/dist/cli/commands/plan.js

@@ -1,5 +1,5 @@
 import { allAdapters, discoverChannels, doctorAgeMs, modelAuthExclusions, probeAll, readDoctor, servableExclusions, servabilityLine } from "../../adapters/registry.js";
-import { formatModelAuthLine, modelLints, ttyVisual } from "../../adapters/model-lints.js";
+import { formatModelAuthLine, contextWindowLints, modelLints, ttyVisual } from "../../adapters/model-lints.js";
 import { collateralLints } from "../../compile/collateral.js";
 import { loadConfig } from "../../config/config.js";
 import { loadGraph } from "../../graph/graph.js";
@@ -71,9 +71,11 @@ export async function plan(_argv, cwd = process.cwd(), adapters = allAdapters())
         lints.push("review: no cross-vendor reviewer pair in fleet — set review.required: false to waive");
     }
     let cost = 0;
+    const routed = [];
     for (const t of g.tasks) {
         try {
             const r = route(t, cfg, channels, profile);
+            routed.push({ taskId: t.id, adapter: r.assignment.adapter, model: r.assignment.model });
             for (const l of r.lints) {
                 const suf = exclusionReason(l);
                 lints.push(suf ? `${l}${suf}` : l);
@@ -104,6 +106,10 @@ export async function plan(_argv, cwd = process.cwd(), adapters = allAdapters())
     }
     if (lints.length)
         lines.push("", "routing lints:", ...lints.map((l) => `  ! ${l}`));
+    // v1.47 T3: advisory only — never blocks plan or --route-strict (run refuses on route().lints only)
+    const windowLints = contextWindowLints(g.tasks, routed, cfg, cwd);
+    if (windowLints.length)
+        lines.push("", "context window lints:", ...windowLints.map((l) => `  ! ${l}`));
     // OBS-12/13/14/21: advisory only — never blocks --route-strict (run refuses on routing lints only)
     const scopeLints = collateralLints(g.tasks, cwd);
     if (scopeLints.length)