tickmarkr 2.5.3 → 2.5.5

package/dist/adapters/registry.js

@@ -578,7 +578,12 @@ export function discoverChannels(cfg, adapters, health, role = "worker") {
         // channel — routing an unknown or 403 into dispatch is fail-closed. Operators with pre-v1.21 doctor.json
         // can opt into the prior unknown-is-routable behavior with routing.allowUnverifiedModels.
         // OBS-117: configured aliases absent from the adapter CLI's own model list are not dispatchable.
-        return a.channels(cfg).filter((c) => !invalid.has(c.model) && modelAuthed(h, c.model, cfg.routing.allowUnverifiedModels) && (!s || s.includes(c.model)));
+        return a.channels(cfg)
+            .filter((c) => !invalid.has(c.model) && modelAuthed(h, c.model, cfg.routing.allowUnverifiedModels) && (!s || s.includes(c.model)))
+            .map((c) => {
+            const identity = h?.modelAuth?.[c.model]?.identity ?? h?.modelIdentities?.[c.model];
+            return identity ? { ...c, identity } : c;
+        });
     });
     if (!cfg.routing.allow && !cfg.routing.deny)
         return base;

package/dist/adapters/types.d.ts

@@ -22,6 +22,7 @@ export interface BillingChannel {
     model: string;
     channel: "sub" | "api";
     tier: Tier;
+    identity?: string;
 }
 export declare const MODEL_PROBE_ERRORS: readonly ["EMFILE", "EAGAIN", "ENFILE", "ENOMEM", "ENOSPC"];
 export type ModelProbeError = typeof MODEL_PROBE_ERRORS[number];
@@ -30,6 +31,7 @@ export interface ModelAuth {
     reason?: string;
     probeError?: ModelProbeError;
     probedAt: string;
+    identity?: string;
 }
 export interface AuthHealth {
     installed: boolean;
@@ -40,6 +42,7 @@ export interface AuthHealth {
     modelsDetectedAt?: string;
     servable?: string[];
     modelAuth?: Record<string, ModelAuth>;
+    modelIdentities?: Record<string, string>;
 }
 export declare function modelAuthed(health: AuthHealth | undefined, model: string, allowUnverifiedModels?: boolean): boolean;
 export interface Invocation {

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

@@ -21,6 +21,7 @@ export interface NewestPark {
     /** The daemon-recorded kind (task-human data.kind), never inferred from prose. */
     kind: string | undefined;
     reason: string | undefined;
+    approveCommand?: string;
     /** The newest failed gate before the park — the gate a waive would satisfy. */
     failedGate: string | undefined;
     /** A pre-dispatch human gate whose reason marks it permanent by design (see isTombstonePark). */

package/dist/cli/commands/approve.js

@@ -1,6 +1,8 @@
+import { graphDefinitionHash, loadGraph, saveGraph } from "../../graph/graph.js";
 import { userInfo } from "node:os";
+import { separabilityErrors } from "../../compile/collateral.js";
 import { GATE_NAMES } from "../../graph/schema.js";
-import { ATTEMPT_CAP_RELEASE, GATE_SATISFIED_RELEASE, Journal, RECHECK_RELEASE, REVIEW_UPHELD_RELEASE } from "../../run/journal.js";
+import { applyScopeAmendments, engagementComparable, ATTEMPT_CAP_RELEASE, GATE_SATISFIED_RELEASE, Journal, RECHECK_RELEASE, REVIEW_UPHELD_RELEASE } from "../../run/journal.js";
 export const APPROVAL_DISPOSITIONS = ["dispatch", "waive-gate", "re-dispatch", "fund-fixed-attempt", "fresh-budget"];
 /**
  * What each disposition's release actually buys — the clause every operator-facing sentence about
@@ -52,6 +54,7 @@ sourceIndexes) {
         const reason = typeof e.data.reason === "string" ? e.data.reason : undefined;
         return {
             index: i, line: (sourceIndexes?.[i] ?? i) + 1, ts: typeof e.ts === "string" ? e.ts : undefined, kind, reason,
+            approveCommand: typeof e.data.approveCommand === "string" ? e.data.approveCommand : undefined,
             failedGate: failedGateForNewestPark(events, taskId, i), tombstone: isTombstonePark(kind, reason),
         };
     }
@@ -73,7 +76,7 @@ export function readJournalEvents(journal) {
  * surface may read it from, so what a menu offers and what the command accepts cannot drift.
  */
 export function permittedDecisionVerbs(park) {
-    if (!park || park.tombstone)
+    if (!park || park.tombstone || park.kind === "scope-request")
         return [];
     if (park.kind === "gate-fail") {
         if (park.failedGate === undefined)
@@ -123,7 +126,7 @@ export function approvalEnactment(token, run) {
 }
 /** The production command registered in COMMANDS; its returned bytes are what the CLI prints. */
 export async function approve(argv, cwd = process.cwd()) {
-    const { runId, taskId, by, reason, waive, uphold, recheck, reviewRoundCeiling } = parseArgs(argv);
+    const { runId, taskId, by, reason, waive, uphold, recheck, reviewRoundCeiling, files } = parseArgs(argv);
     const decisions = [waive, uphold, recheck].filter(Boolean).length;
     if (decisions > 1)
         throw new Error("--waive, --uphold and --recheck are different decisions — pass one");
@@ -148,6 +151,41 @@ export async function approve(argv, cwd = process.cwd()) {
         const gateFailPark = park?.kind === "gate-fail";
         const infraPark = park?.kind === "infra";
         const failedGate = gateFailPark ? park?.failedGate : undefined;
+        if ((park?.kind === "scope-request" && !decisions) || files !== undefined) {
+            if (park?.kind !== "scope-request")
+                throw new Error("--files requires a scope-request park");
+            if (!files?.length)
+                throw new Error(`scope-request for ${taskId} requires --files <glob,…>`);
+            if (decisions)
+                throw new Error("--files cannot be combined with --waive, --uphold or --recheck");
+            const graph = applyScopeAmendments(loadGraph(cwd), journal);
+            const from = graphDefinitionHash(graph);
+            if (!engagementComparable(journal.read(), from).comparable
+                || (lastHuman?.data.graphDefinitionHash !== undefined && lastHuman.data.graphDefinitionHash !== from)) {
+                throw new Error(`refusing stale scope-request approval for ${taskId}: graph revision changed`);
+            }
+            const task = graph.tasks.find((t) => t.id === taskId);
+            if (!task)
+                throw new Error(`unknown task ${taskId}`);
+            const amendedFiles = [...new Set([...task.files, ...files])];
+            if (amendedFiles.length === task.files.length)
+                throw new Error("--files must extend the parked files[] revision");
+            const amended = { ...graph, tasks: graph.tasks.map((t) => t.id === taskId ? { ...t, files: amendedFiles } : t) };
+            const conflicts = separabilityErrors(amended.tasks);
+            if (conflicts.length)
+                throw new Error(`refusing scope-request approval for ${taskId}: ${conflicts.join("\n")}`);
+            journal.append("task-approved", taskId, {
+                by, ...(reason ? { reason } : {}), via: "cli", release: "scope-request",
+                amendment: { from, to: graphDefinitionHash(amended), beforeFiles: task.files, files: amendedFiles, parkLine: park.line },
+            });
+            // Do not write graph.json from this process while the daemon owns it: its sweep materializes
+            // the amendment without replacing a sibling's running state with this command's snapshot.
+            const projected = applyScopeAmendments(graph, journal);
+            const owner = approvalRunOwner(cwd, runId);
+            if (!owner.live && !owner.blockingRunId)
+                saveGraph(cwd, projected);
+            return disposition(cwd, runId, "dispatch", `approved files[] for ${taskId} in ${runId} — by ${by}`, serialization.contended);
+        }
         if (gateFailPark && !failedGate) {
             throw new Error(`task ${taskId} is parked on gate-fail but has no failed gate result on the newest park — refusing to infer one`);
         }
@@ -247,11 +285,12 @@ function disposition(cwd, runId, token, message, contended) {
     };
     return `${out}\nTICKMARKR_APPROVAL ${JSON.stringify(record)}`;
 }
-const USAGE = "usage: tickmarkr approve <run-id> <task-id> [--waive|--uphold|--recheck] [--review-rounds <positive-integer>] [--by <name>] [--reason <text>]";
+const USAGE = "usage: tickmarkr approve <run-id> <task-id> [--files <glob,…>] [--waive|--uphold|--recheck] [--review-rounds <positive-integer>] [--by <name>] [--reason <text>]";
 // hand-parsed argv — no CLI framework (house style). Positionals are runId then taskId; decision,
 // ceiling, actor and reason are flags. Throws usage on missing positionals (mirrors resume.ts/unlock.ts).
 function parseArgs(argv) {
     const positionals = [];
+    let files;
     let by;
     let reason;
     let waive = false;
@@ -260,7 +299,16 @@ function parseArgs(argv) {
     let reviewRoundCeiling;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
-        if (a === "--by") {
+        if (a === "--files") {
+            const value = argv[++i];
+            if (!value || value.startsWith("--"))
+                throw new Error("--files requires <glob,…>");
+            files = value.split(",").map((file) => file.trim());
+            if (files.some((file) => !file || file.startsWith("/") || file.startsWith("!") || file.split("/").includes(".."))) {
+                throw new Error("--files requires non-empty repository-relative globs");
+            }
+        }
+        else if (a === "--by") {
             by = argv[++i];
             if (!by)
                 throw new Error(USAGE);
@@ -296,7 +344,7 @@ function parseArgs(argv) {
     if (!runId || !taskId) {
         throw new Error(USAGE);
     }
-    return { runId, taskId, by: by ?? userInfo().username, reason, waive, uphold, recheck, reviewRoundCeiling };
+    return { runId, taskId, by: by ?? userInfo().username, reason, waive, uphold, recheck, reviewRoundCeiling, files };
 }
 function failedGateForNewestPark(events, taskId, lastHumanIndex) {
     for (let i = lastHumanIndex - 1; i >= 0; i -= 1) {

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

@@ -128,6 +128,7 @@ export declare function doctorProbePreflight(cwd?: string, cfg?: {
         }>;
         floors: Record<string, "cheap" | "mid" | "frontier">;
         learned: "on" | "off";
+        escalateTier: "on" | "off";
         allowUnverifiedModels: boolean;
         mode?: "partner-led" | "risk-based" | "staff-led" | undefined;
         learnedTuning?: {
@@ -185,6 +186,7 @@ export declare function doctorProbePreflight(cwd?: string, cfg?: {
         complexityThreshold: number;
         timeoutMs: number;
         required: boolean;
+        floor: "cheap" | "mid" | "frontier" | "worker";
         prefer?: string[] | undefined;
         policy?: "full" | "judge-only" | undefined;
         criticalPaths?: string[] | undefined;
@@ -245,6 +247,7 @@ export declare function cachedDoctorDiagnostics(cwd?: string, adapters?: WorkerA
         }>;
         floors: Record<string, "cheap" | "mid" | "frontier">;
         learned: "on" | "off";
+        escalateTier: "on" | "off";
         allowUnverifiedModels: boolean;
         mode?: "partner-led" | "risk-based" | "staff-led" | undefined;
         learnedTuning?: {
@@ -302,6 +305,7 @@ export declare function cachedDoctorDiagnostics(cwd?: string, adapters?: WorkerA
         complexityThreshold: number;
         timeoutMs: number;
         required: boolean;
+        floor: "cheap" | "mid" | "frontier" | "worker";
         prefer?: string[] | undefined;
         policy?: "full" | "judge-only" | undefined;
         criticalPaths?: string[] | undefined;

package/dist/cli/commands/doctor.js

@@ -613,6 +613,46 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
     if (probeProgressTTY && probeOk + probeBad > 0) {
         process.stderr.write(`\r\x1b[2K  probed ${probeOk + probeBad} channels · ${probeOk} ok${probeBad ? ` · ${probeBad} failed` : ""}\n`);
     }
+    const identityResolver = opts.resolveClaudeAliasIdentity
+        ?? (adapters.some((a) => a.id === claudeCode.id) ? resolveClaudeAliasIdentity : undefined);
+    const aliasDriftFindings = [];
+    // Single pre-write snapshot of the resolver's outcome per alias (including undefined/failure).
+    // Catalog rendering below reads only this map — never calls the resolver again — so a transient
+    // resolver that succeeds on a later call can never produce a result that stays display-only
+    // while doctor.json and discovery keep the earlier undefined/failed outcome.
+    const resolvedIdentitySnapshot = {};
+    if (identityResolver && health["claude-code"]?.installed) {
+        const configured = cfg.tiers["claude-code"]?.models ?? {};
+        for (const [alias, stampedIdentity] of Object.entries(CLAUDE_ALIAS_IDENTITY_STAMPS)) {
+            if (!(alias in configured))
+                continue;
+            let resolvedIdentity;
+            try {
+                resolvedIdentity = identityResolver(cwd, alias);
+            }
+            catch {
+                resolvedIdentitySnapshot[alias] = undefined;
+                continue; // advisory source failure is unknown, never a doctor failure
+            }
+            resolvedIdentitySnapshot[alias] = resolvedIdentity;
+            if (resolvedIdentity) {
+                if (!health["claude-code"].modelAuth) {
+                    health["claude-code"].modelAuth = {};
+                }
+                const existing = health["claude-code"].modelAuth[alias] ?? {
+                    authed: true,
+                    probedAt: new Date().toISOString(),
+                };
+                health["claude-code"].modelAuth[alias] = {
+                    ...existing,
+                    identity: resolvedIdentity,
+                };
+            }
+            if (resolvedIdentity && resolvedIdentity !== stampedIdentity) {
+                aliasDriftFindings.push(`resolved-identity drift: claude-code:${alias} resolved to ${resolvedIdentity}, stamped identity ${stampedIdentity} — reclassify per benchmark policy (advisory — routing unchanged)`);
+            }
+        }
+    }
     writeDoctor(cwd, health);
     const rows = adapters.map((a) => {
         const h = health[a.id];
@@ -752,37 +792,12 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
     // v1.65 T3: hardcoded-flag drift — advisory warn rows only. Runs AFTER writeDoctor so the verdicts
     // can never leak into doctor.json, and discoverChannels/routing never read them.
     lintRows.push(...flagDriftWarnings(adapters, health).map(attentionRow));
-    // OBS-145: resolved-identity drift is the same class of display-only doctor warning. Stamps live
-    // beside the alias-owning adapter; the comparison runs only for configured floating aliases and
-    // never enters health/doctor.json, config, channel discovery, learned profiles, or route().
-    const identityResolver = opts.resolveClaudeAliasIdentity
-        ?? (adapters.includes(claudeCode) ? resolveClaudeAliasIdentity : undefined);
-    if (identityResolver && health["claude-code"]?.installed) {
-        const configured = cfg.tiers["claude-code"]?.models ?? {};
-        for (const [alias, stampedIdentity] of Object.entries(CLAUDE_ALIAS_IDENTITY_STAMPS)) {
-            if (!(alias in configured))
-                continue;
-            let resolvedIdentity;
-            try {
-                resolvedIdentity = identityResolver(cwd, alias);
-            }
-            catch {
-                continue; // advisory source failure is unknown, never a doctor failure
-            }
-            if (resolvedIdentity && resolvedIdentity !== stampedIdentity) {
-                lintRows.push(attentionRow(`resolved-identity drift: claude-code:${alias} resolved to ${resolvedIdentity}, stamped identity ${stampedIdentity} — reclassify per benchmark policy (advisory — routing unchanged)`));
-            }
-        }
-    }
+    // OBS-145: resolved-identity drift is advisory display warning.
+    lintRows.push(...aliasDriftFindings.map(attentionRow));
     const resolvedCatalogModel = (adapter, model) => {
-        if (adapter !== "claude-code" || !identityResolver || !(model in CLAUDE_ALIAS_IDENTITY_STAMPS))
+        if (adapter !== "claude-code" || !(model in CLAUDE_ALIAS_IDENTITY_STAMPS))
             return undefined;
-        try {
-            return identityResolver(cwd, model);
-        }
-        catch {
-            return undefined;
-        }
+        return resolvedIdentitySnapshot[model];
     };
     // MODEL-05/06: print-only drift fragment; advisory, whole-line-commented additions, tickmarkr NEVER applies it.
     // TTY gets a one-line summary + the fragment as a file (the full dump drowned everything else,

package/dist/cli/commands/fleet.js

@@ -5,13 +5,13 @@ import { allAdapters, discoverChannels, doctorAgeMs, initDoctorReuse, modelAuthE
 import { catalogModelAdvisory, catalogTierRanking, declaredModelWindow, fleetUnclassifiedModels } from "../../adapters/model-lints.js";
 import { CATALOG_REFRESH_TIMEOUT_MS, formatCatalogRefreshLegs, readCachedCatalog, refreshCatalogCommand } from "../../adapters/catalog-remote.js";
 import { CLAUDE_ALIAS_IDENTITY_STAMPS, readClaudeAliasIdentity } from "../../adapters/claude-code.js";
-import { fleetEditableFromConfig, fleetEditableEquals, formatFleetPrint, globalConfigDir, overlayBytesLoadError, renderFleetOverlayWrite, repoOverlayPath, ROUTING_MODES, unifiedYamlDiff, } from "../../config/config.js";
-import { projectFleetWhy, renderFleetWhy } from "../../config/fleet-why.js";
+import { fleetEditableFromConfig, fleetEditableEquals, formatFleetPrint, globalConfigDir, loadConfigWithMode, overlayBytesLoadError, readOverlayFile, renderFleetOverlayWrite, repoOverlayPath, ROUTING_MODES, TIER_RANK, unifiedYamlDiff, } from "../../config/config.js";
+import { exclusionReason, projectFleetWhy, renderFleetWhy } from "../../config/fleet-why.js";
 import { SHAPES, TIERS } from "../../graph/schema.js";
 import { doctor } from "./doctor.js";
 import { candidateRow, costSignal, shapeCandidates } from "./fleet-picker.js";
 import { route } from "../../route/router.js";
-import { disallowedBy } from "../../route/preference.js";
+import { denyPreferCollisionLine, denyPreferCollisions, disallowedBy, entryMatchesChannel, exclusionCollector } from "../../route/preference.js";
 import { resolveRunMode } from "../../run/daemon.js";
 import { loadRoutingProfile } from "../../run/journal.js";
 const initialFetch = globalThis.fetch;
@@ -202,10 +202,17 @@ export async function assembleFleetEditor(cwd, adapters, io, opts) {
     const previewChannels = discoverChannels({ ...cfg, routing: routingScopeBlind }, adapters, health);
     const universe = adapters
         .filter((adapter) => health[adapter.id]?.installed)
-        .map((adapter) => ({
-        adapter: adapter.id,
-        models: [...new Set(previewChannels.filter((c) => c.adapter === adapter.id).map((c) => c.model))],
-    }));
+        .map((adapter) => {
+        const served = previewChannels.filter((c) => c.adapter === adapter.id);
+        // LEG2-T3 round 2 finding 3: the recorded identity per channel, so the editable membership
+        // matches allow/deny entries with the same authority the collector and the browser use
+        const identities = Object.fromEntries(served.flatMap((c) => (c.identity ? [[c.model, c.identity]] : [])));
+        return {
+            adapter: adapter.id,
+            models: [...new Set(served.map((c) => c.model))],
+            ...(Object.keys(identities).length ? { identities } : {}),
+        };
+    });
     const initial = fleetEditableFromConfig(cfg, universe);
     const editable = structuredClone(initial);
     // OBS-508: the same catalog evidence doctor's drift overlay prints now rides each unclassified
@@ -250,9 +257,14 @@ export async function assembleFleetEditor(cwd, adapters, io, opts) {
         || a.model.localeCompare(b.model));
     // OBS-508 follow-through: the browser renders the metadata the assembler always had — catalog
     // ctx/price evidence and doctor's model-probe wall clock — as columns instead of dropping them.
+    // OBS-972/FL-1: the same alias→identity doctor recorded (modelAuth.identity, falling back to
+    // the coarser per-adapter modelIdentities map registry.ts/preference.ts already read for
+    // routing exclusion) — a floating alias's resolved concrete model id.
+    const resolvedModelIdentity = (adapter, model) => health[adapter]?.modelAuth?.[model]?.identity ?? health[adapter]?.modelIdentities?.[model];
     const rowEvidence = (adapter, model, evidence) => {
         const probed = health[adapter]?.modelAuth?.[model];
         const contextWindow = evidence?.contextWindow ?? declaredModelWindow(cfg, adapter, model);
+        const identity = resolvedModelIdentity(adapter, model);
         const out = {
             ...(contextWindow !== undefined ? { contextWindow } : {}),
             ...(evidence?.outputWindow !== undefined ? { outputWindow: evidence.outputWindow } : {}),
@@ -262,6 +274,8 @@ export async function assembleFleetEditor(cwd, adapters, io, opts) {
             // OBS-519: doctor already recorded the failed verdict — a rate-limited/unauthed model must
             // not render identically to a healthy row on the surface that edits its fleet membership.
             ...(probed?.authed === false ? { unauthed: probed.reason ?? "probe failed" } : {}),
+            // the browser decides deny coverage itself, over the STAGED policy (LEG2-T3 finding 1)
+            ...(identity !== undefined ? { identity } : {}),
         };
         return Object.keys(out).length > 0 ? out : undefined;
     };
@@ -306,24 +320,42 @@ export async function assembleFleetEditor(cwd, adapters, io, opts) {
     ]));
     const channels = discoverChannels(cfg, adapters, health);
     const profile = loadRoutingProfile(cwd, cfg, { preview: true });
+    const stagedEditable = (map, deny) => ({
+        ...structuredClone(initial),
+        denyAdapters: deny.adapters,
+        denyModels: deny.models,
+        denyWorkersAdapters: deny.workersAdapters,
+        denyWorkersModels: deny.workersModels,
+        map,
+    });
+    const candidateMemo = new Map();
     const previewCfg = (mode, map, deny) => {
-        // mirror the writer: only the adapters/models scopes are fleet-editable; workers deny survives
-        const nextDeny = { ...cfg.routing.deny };
-        if (deny.adapters.length)
-            nextDeny.adapters = deny.adapters;
-        else
-            delete nextDeny.adapters;
-        if (deny.models.length)
-            nextDeny.models = deny.models;
-        else
-            delete nextDeny.models;
-        const routing = {
-            ...routingScopeBlind,
-            map,
-            floors: modeCfgs[mode].cfg.routing.floors,
-            ...(Object.keys(nextDeny).length ? { deny: nextDeny } : {}),
-        };
-        return { ...cfg, routing };
+        const key = JSON.stringify([mode, map, deny]);
+        const hit = candidateMemo.get(key);
+        if (hit)
+            return hit;
+        let preview;
+        try {
+            const bytes = renderFleetOverlayWrite(currentRepoOverlayText(cwd), {
+                initial,
+                edited: stagedEditable(map, deny),
+                universe,
+                ...(mode !== rm.mode.mode ? { mode } : {}),
+            });
+            preview = { ok: true, cfg: loadConfigWithMode(cwd, { globalDir, repoOverlayText: bytes }).cfg };
+        }
+        catch (error) {
+            preview = { ok: false, error: error.message.replace(/\s+/g, " ").trim() };
+        }
+        if (candidateMemo.size > 32)
+            candidateMemo.clear();
+        candidateMemo.set(key, preview);
+        return preview;
+    };
+    const previewUnavailable = (error) => `preview unavailable (${error}) — the staged overlay does not load, so w would be refused`;
+    const stagedRouting = (deny) => {
+        const preview = previewCfg(rm.mode.mode, editable.map, deny);
+        return preview.ok ? { ok: true, routing: preview.cfg.routing } : preview;
     };
     // route() never deny-filters its pool — that contract lives in discoverChannels — so every
     // preview call rebuilds the pool the staged deny would discover
@@ -333,7 +365,10 @@ export async function assembleFleetEditor(cwd, adapters, io, opts) {
         let subs = 0;
         let apiN = 0;
         let apiUsd = 0;
-        const cfgPreview = previewCfg(mode, map, deny);
+        const preview = previewCfg(mode, map, deny);
+        if (!preview.ok)
+            return `  mix: ${previewUnavailable(preview.error)}`;
+        const cfgPreview = preview.cfg;
         const pool = previewPool(cfgPreview);
         for (const shape of SHAPES) {
             try {
@@ -393,7 +428,15 @@ export async function assembleFleetEditor(cwd, adapters, io, opts) {
             : { declaredAt: "routing.mode" };
     };
     const projectedShapeRows = (mode, map, deny) => {
-        const cfgPreview = previewCfg(mode, map, deny);
+        const preview = previewCfg(mode, map, deny);
+        if (!preview.ok) {
+            return projectFleetWhy(SHAPES.map((shape) => ({
+                id: shape,
+                effective: previewUnavailable(preview.error),
+                ...whyDeclaration(shape, mode, map, false),
+            })), { repoRoot: cwd, globalDir });
+        }
+        const cfgPreview = preview.cfg;
         const pool = previewPool(cfgPreview);
         const values = SHAPES.map((shape) => {
             try {
@@ -433,13 +476,13 @@ export async function assembleFleetEditor(cwd, adapters, io, opts) {
     const unauthedClis = adapters
         .filter((adapter) => health[adapter.id]?.installed && health[adapter.id]?.authed === false)
         .map((adapter) => adapter.id);
-    const unauthedModelCount = modelAuthExclusions(cfg, adapters, health).length;
-    const excludedNoteFor = (deny) => {
+    const unauthedModels = modelAuthExclusions(cfg, adapters, health);
+    const unauthedModelCount = unauthedModels.length;
+    const excludedNoteFor = (cfgPreview) => {
         let stagedOut = 0;
         let denied = 0;
-        const stagedRouting = previewCfg(rm.mode.mode, {}, deny).routing;
         for (const channel of previewChannels) {
-            if (disallowedBy(channel, stagedRouting) === null)
+            if (disallowedBy(channel, cfgPreview.routing) === null)
                 continue;
             if (disallowedBy(channel, cfg.routing) === null)
                 stagedOut += 1;
@@ -459,14 +502,122 @@ export async function assembleFleetEditor(cwd, adapters, io, opts) {
             parts.push(`${unclassifiedRows.length} unclassified (never routed)`);
         return parts.length ? `not offered: ${parts.join(" · ")} — the models view explains each row` : undefined;
     };
+    // OBS-994/FL-1: the nine mechanisms outside the deny scopes that can keep a channel off a
+    // shape's candidate list each get a reason or an explicit "not manageable here" caption — a
+    // silent omission is indistinguishable from a bug (OBS-530's lesson, extended past deny/allow).
+    // allow and the unauthed probe already carry a reason through excludedNoteFor above; the rest
+    // are shape-scoped (a pin/pool/floor/prefer excludes only for THIS shape) and belong here.
+    const shapeExclusionCaptions = (shape, map, cfgPreview) => {
+        const pool = previewPool(cfgPreview);
+        const entry = map[shape];
+        const captions = [];
+        // 2. pin or pool — a closed candidate set declared for this shape; a channel outside it is
+        // not manageable from the models view, it is a Shapes-view declaration.
+        if (entry?.pin) {
+            captions.push(`pin: routing.map.${shape}.pin fixes this shape to ${entry.pin.via}:${entry.pin.model} — not manageable here, edit it in Shapes`);
+        }
+        else if (entry?.pool) {
+            const declared = new Set(entry.pool.channels);
+            const outside = pool.filter((c) => !declared.has(`${c.adapter}:${c.model}`));
+            if (outside.length) {
+                captions.push(`pool: ${outside.length} channel(s) outside routing.map.${shape}.pool's declared set — not manageable here, edit it in Shapes`);
+            }
+        }
+        // 3. floor — channels below this shape's minimum tier.
+        const floor = cfgPreview.routing.floors[shape];
+        if (floor) {
+            const belowFloor = pool.filter((c) => TIER_RANK[c.tier] < TIER_RANK[floor]);
+            if (belowFloor.length) {
+                captions.push(`floor: ${belowFloor.length} channel(s) below routing.floors.${shape} (${floor}) — not manageable here, edit the floor in Shapes`);
+            }
+        }
+        // 5. tombstones — the repo overlay's OWN null over this shape's map entry, masking a lower
+        // (global/default) layer's declaration rather than expressing a value of its own.
+        const repoRaw = readOverlayFile(repoOverlayPath(cwd));
+        const rawEntry = repoRaw.routing?.map?.[shape];
+        if (rawEntry === null) {
+            captions.push(`tombstone: routing.map.${shape}: null masks a lower layer's declaration — not manageable here, edit the repo overlay directly`);
+        }
+        else if (rawEntry && "pool" in rawEntry && rawEntry.pool === null) {
+            captions.push(`tombstone: routing.map.${shape}.pool: null masks a lower layer's pool — not manageable here, edit the repo overlay directly`);
+        }
+        else if (rawEntry && "pin" in rawEntry && rawEntry.pin === null) {
+            captions.push(`tombstone: routing.map.${shape}.pin: null masks a lower layer's pin — not manageable here, edit the repo overlay directly`);
+        }
+        // 6. explore/learned knobs — global routing settings, never a per-channel fleet toggle.
+        if (cfgPreview.routing.explore?.mode === "off") {
+            captions.push("explore: routing.explore.mode is off — a global knob, not manageable here");
+        }
+        if (cfgPreview.routing.learned === "off") {
+            captions.push("learned: routing.learned is off — a global knob, not manageable here");
+        }
+        // 7. task hint — a shape's prefer bias is authored in Shapes/spec, not per-channel in fleet.
+        if (entry?.prefer?.length) {
+            captions.push(`task hint: routing.map.${shape}.prefer ranks ${entry.prefer.join(", ")} — not manageable here, edit it in Shapes`);
+        }
+        // 8. deny∩prefer collision — a standing lint on this shape's declaration, never a fleet toggle.
+        for (const collision of denyPreferCollisions(cfgPreview, [shape])) {
+            captions.push(denyPreferCollisionLine(collision));
+        }
+        // 9. first-match provenance — the per-channel ledger below lists EVERY collector scope.
+        return captions;
+    };
+    // LEG2-T3 finding 1: each channel a mechanism touches on this shape gets its own ledger row
+    // naming every reason — collector scopes with their config paths (allow, flat and workers deny,
+    // all of them, never a first match), the unauthed probe, pin/pool/floor, the task hint and a
+    // deny∩prefer collision it is the target of — or that leaves the shape with no candidate at all.
+    const channelLedger = (shape, map, cfgPreview, offered) => {
+        const entry = map[shape];
+        const floor = cfgPreview.routing.floors[shape];
+        const collisions = denyPreferCollisions(cfgPreview, [shape]);
+        const discovered = new Set(previewChannels.map((c) => `${c.adapter}:${c.model}`));
+        // discovery already dropped a channel whose model probe failed — it still gets its own row
+        const unauthedRows = [
+            ...unauthedClis.map((adapter) => `${adapter} — CLI unauthed — re-probe with tickmarkr doctor`),
+            ...unauthedModels.filter(({ key }) => !discovered.has(key))
+                .map(({ key, reason }) => `${key.replace(":", "/")} — unauthed (${reason}) — re-probe with tickmarkr doctor`),
+        ];
+        return [...unauthedRows, ...previewChannels.flatMap((c) => {
+                const key = `${c.adapter}:${c.model}`;
+                const reasons = exclusionCollector(c, cfgPreview.routing, "worker").map(exclusionReason);
+                if (health[c.adapter]?.authed === false)
+                    reasons.push(`${c.adapter} CLI unauthed — re-probe with tickmarkr doctor`);
+                else if (health[c.adapter]?.modelAuth?.[c.model]?.authed === false)
+                    reasons.push("unauthed — re-probe with tickmarkr doctor");
+                if (entry?.pin && key !== `${entry.pin.via}:${entry.pin.model}`) {
+                    reasons.push(`not routing.map.${shape}.pin (${entry.pin.via}:${entry.pin.model}) — not manageable here`);
+                }
+                if (entry?.pool && !entry.pool.channels.includes(key)) {
+                    reasons.push(`outside routing.map.${shape}.pool — not manageable here`);
+                }
+                if (floor && TIER_RANK[c.tier] < TIER_RANK[floor]) {
+                    reasons.push(`below routing.floors.${shape} (${floor}) — not manageable here`);
+                }
+                if (entry?.prefer?.some((p) => entryMatchesChannel(p, c))) {
+                    reasons.push(`task hint: routing.map.${shape}.prefer names it — not manageable here`);
+                }
+                for (const collision of collisions) {
+                    const named = collision.detail.split(" > ").some((p) => entryMatchesChannel(p, c));
+                    if (named || offered.size === 0)
+                        reasons.push(denyPreferCollisionLine(collision));
+                }
+                // labelled like the models view's row (adapter/model), so a ledger row never reads as a candidate
+                return reasons.length ? [`${c.adapter}/${c.model} — ${reasons.join("; ")}`] : [];
+            })];
+    };
     const candidatesForShape = (shape, mode, map, deny) => {
-        const cfgPreview = previewCfg(mode, map, deny);
+        const preview = previewCfg(mode, map, deny);
+        if (!preview.ok)
+            return { rows: [], excludedNote: previewUnavailable(preview.error) };
+        const cfgPreview = preview.cfg;
         const rows = shapeCandidates(previewTask(shape), cfgPreview, previewPool(cfgPreview), profile).map((candidate) => ({
             id: `${candidate.assignment.adapter}:${candidate.assignment.model}`,
             label: candidateRow(candidate, cfg.pricing),
             pin: { via: candidate.assignment.adapter, model: candidate.assignment.model },
         }));
-        return { rows, excludedNote: excludedNoteFor(deny) };
+        const offered = new Set(rows.map((row) => row.id));
+        const notes = [excludedNoteFor(cfgPreview), ...shapeExclusionCaptions(shape, map, cfgPreview)].filter((note) => note !== undefined);
+        return { rows, excludedNote: notes.length ? notes.join("\n") : undefined, ledger: channelLedger(shape, map, cfgPreview, offered) };
     };
     const preferUniverse = [
         ...new Set(channels.flatMap((channel) => [
@@ -493,6 +644,9 @@ export async function assembleFleetEditor(cwd, adapters, io, opts) {
         const staged = structuredClone(initial);
         staged.denyAdapters = state.denyAdapters;
         staged.denyModels = state.denyModels;
+        // OBS-994/FL-1: the workers-only deny scope rides the same review/write funnel as the flat one.
+        staged.denyWorkersAdapters = state.denyWorkersAdapters;
+        staged.denyWorkersModels = state.denyWorkersModels;
         staged.map = state.map;
         const today = new Date().toISOString().slice(0, 10);
         for (const classification of state.classifications) {
@@ -545,6 +699,8 @@ export async function assembleFleetEditor(cwd, adapters, io, opts) {
         health,
         initialDenyAdapters: editable.denyAdapters,
         initialDenyModels: editable.denyModels,
+        initialDenyWorkersAdapters: editable.denyWorkersAdapters,
+        initialDenyWorkersModels: editable.denyWorkersModels,
         modelGroups,
         initialMode: rm.mode.mode,
         modeOptions: ROUTING_MODES.map((mode) => ({ id: mode, gloss: MODE_GLOSS[mode] })),
@@ -560,6 +716,7 @@ export async function assembleFleetEditor(cwd, adapters, io, opts) {
         steeringOptionsFor,
         reviewOverlay,
         reloadGuard,
+        stagedRouting,
         entry: opts.entry,
         initialJudge,
         judgeSeats: seats,
@@ -607,6 +764,11 @@ export async function assembleFleetEditor(cwd, adapters, io, opts) {
     return {
         props,
         commit,
-        renderWhy: () => renderFleetWhy(projectedShapeRows(rm.mode.mode, editable.map, { adapters: editable.denyAdapters, models: editable.denyModels })),
+        renderWhy: () => renderFleetWhy(projectedShapeRows(rm.mode.mode, editable.map, {
+            adapters: editable.denyAdapters,
+            models: editable.denyModels,
+            workersAdapters: editable.denyWorkersAdapters ?? [],
+            workersModels: editable.denyWorkersModels ?? [],
+        })),
     };
 }