catherd-cli 1.3.0 → 1.5.0

package/src/domain/select.ts

@@ -9,6 +9,8 @@ import {
 } from "./catalog.ts";
 import { type BillingMode, type Cost, compareCost, costOf, DEFAULT_BILLING } from "./cost.ts";
 import { CatherdError } from "./errors.ts";
+import { quotaOf } from "./failover.ts";
+import { tryParseRung } from "./ids.ts";
 import { DIFFICULTIES, type Difficulty, type Kind } from "./lane.ts";
 import type { Role } from "./roles.ts";
 
@@ -17,6 +19,11 @@ export interface RoutingProfile {
   objective: "cost" | "speed";
   billing: Partial<Record<string, BillingMode>>;
   role: { enabled: boolean; rungs: string[]; defaultRung?: string };
+  /**
+   * spec 1.5 plan 24: the run's dispatches so far per quota (`quotaOf`), the headroom a tie between rungs of
+   * equal scores is broken on; absent, every quota counts 0 and the candidates' order breaks it
+   */
+  usage?: Partial<Record<string, number>>;
 }
 
 export interface Candidate {
@@ -31,6 +38,10 @@ export interface Candidate {
 export interface Pick {
   rung: string;
   ladder: string[];
+  /** spec 1.5 plan 24: no rung clears the lane's bar (`no rung clears repo_code/hard; best is …`) */
+  noClear?: string;
+  /** spec 1.5 plan 24: rungs of equal scores competed for the start, and how the tie was broken */
+  tie?: string;
 }
 
 const byNull = (a: number | null, b: number | null) =>
@@ -44,12 +55,14 @@ function secsOf(c: Catalog, canonical: string, kind: Kind | null): number | null
  * The role's enabled rungs that the catalog can place: parseable, offered by their model, listed by
  * the backend when it has a listing, capable for the role, and scored (their own or a treat-like).
  * Ordered by cost (spec §5.3), or by measured speed with cost breaking ties; with fewer than 5
- * samples a rung has no speed, and cost orders it, which within a model is effort order.
+ * samples a rung has no speed, and cost orders it, which within a model is effort order. The profile's
+ * ladder order breaks every remaining tie (spec 1.5 plan 24), so equal rungs start in the order the user wrote.
  */
 export function candidates(c: Catalog, p: RoutingProfile, role: Role, kind: Kind | null = null): Candidate[] {
   if (!p.role.enabled) return [];
   const out: Candidate[] = [];
-  for (const rung of new Set(p.role.rungs)) {
+  const order = [...new Set(p.role.rungs)];
+  for (const rung of order) {
     let info: RungInfo;
     try {
       info = rungInfo(c, rung);
@@ -68,8 +81,11 @@ export function candidates(c: Catalog, p: RoutingProfile, role: Role, kind: Kind
       secs: secsOf(c, info.canonical, kind),
     });
   }
-  const cost = (a: Candidate, b: Candidate) => compareCost(a.cost, b.cost) || byNull(a.secs, b.secs);
-  const speed = (a: Candidate, b: Candidate) => byNull(a.secs, b.secs) || compareCost(a.cost, b.cost);
+  const written = (a: Candidate, b: Candidate) => order.indexOf(a.rung) - order.indexOf(b.rung);
+  const cost = (a: Candidate, b: Candidate) =>
+    compareCost(a.cost, b.cost) || byNull(a.secs, b.secs) || written(a, b);
+  const speed = (a: Candidate, b: Candidate) =>
+    byNull(a.secs, b.secs) || compareCost(a.cost, b.cost) || written(a, b);
   return out.sort(p.objective === "speed" ? speed : cost);
 }
 
@@ -85,15 +101,94 @@ function noRung(role: Role): CatherdError {
   });
 }
 
+/** The dimensions a ladder is compared on: the bar's, else every dimension the start has a value on. */
+function compareDims(start: Candidate, bar: Partial<Record<Dim, number>>): Dim[] {
+  const dims = (Object.keys(bar) as Dim[]).filter((d) => bar[d] !== undefined);
+  return dims.length ? dims : (Object.keys(start.scores) as Dim[]);
+}
+
+/** `x` scores at least `start` on every one of `dims` (a missing value scores below any). */
+const atLeast = (x: Candidate, start: Candidate, dims: Dim[]): boolean =>
+  dims.every(
+    (d) => (x.scores[d] ?? Number.NEGATIVE_INFINITY) >= (start.scores[d] ?? Number.NEGATIVE_INFINITY),
+  );
+
+/** Spec 1.5 plan 24: how many of `rungs` (a run's dispatched rungs) drew on each quota. */
+export function quotaUsage(rungs: readonly string[]): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const rung of rungs) {
+    const r = tryParseRung(rung);
+    if (r) out[quotaOf(r)] = (out[quotaOf(r)] ?? 0) + 1;
+  }
+  return out;
+}
+
+/** Equal on every one of `dims`: a tie for the start. */
+const same = (a: Candidate, b: Candidate, dims: Dim[]): boolean => atLeast(a, b, dims) && atLeast(b, a, dims);
+
+const quota = (x: Candidate): string => quotaOf(x.info.parsed);
+
+/**
+ * Spec 1.5 plan 24: when rungs on other quotas score exactly as `start` does on `dims`, the start goes to the
+ * quota with the most headroom (the fewest of the run's dispatches so far), the candidates' order (cost, then
+ * the profile's ladder order) breaking an equal count. `tie` says what decided. Rungs of one quota that tie
+ * are no tie (cost already orders them), nor is a rung of another cost tier.
+ */
+function breakTie(
+  start: Candidate,
+  order: Candidate[],
+  dims: Dim[],
+  usage: Partial<Record<string, number>>,
+): { start: Candidate; tie?: string } {
+  // a metered rung never wins a tie over a plan's: headroom is free only within the start's cost tier
+  const rivals = order.filter(
+    (x) =>
+      x !== start && quota(x) !== quota(start) && x.cost.tier === start.cost.tier && same(x, start, dims),
+  );
+  if (rivals.length === 0) return { start };
+  const used = (x: Candidate) => usage[quota(x)] ?? 0;
+  const tied = [start, ...rivals];
+  const pick = [...tied].sort((a, b) => used(a) - used(b))[0] as Candidate;
+  const others = tied.filter((x) => x !== pick).map((x) => x.rung);
+  const counts = [...new Set(tied.map(quota))].map((q) => `${q} ${usage[q] ?? 0}`).join(", ");
+  const why = tied.every((x) => used(x) === used(pick))
+    ? `equal headroom (${used(pick)} dispatches each); the profile's ladder order and cost decided`
+    : `${quota(pick)} has the most headroom (dispatches in this run: ${counts})`;
+  return {
+    start: pick,
+    tie: `tie on ${dims.join(", ")} with ${others.join(", ")}: started on ${pick.rung}; ${why}`,
+  };
+}
+
+/**
+ * Spec 1.5 plan 24, "climb ladders only go up": the start (after a tie on equal scores goes to the quota with
+ * the most headroom), then, in `order`'s order, every other candidate that scores at least the last rung kept
+ * on `dims`. A stronger rung is on the ladder wherever cost puts it, and one weaker than the rung before it
+ * never is (checking each against the start alone let a cheaper, weaker rung follow a stronger one), so a
+ * climb never lands on a rung below the one it leaves.
+ */
+function ladderFrom(
+  first: Candidate,
+  order: Candidate[],
+  dims: Dim[],
+  usage: Partial<Record<string, number>> = {},
+): Pick {
+  const { start, tie } = breakTie(first, order, dims, usage);
+  const kept = [start];
+  for (const x of order) if (x !== start && atLeast(x, kept.at(-1) as Candidate, dims)) kept.push(x);
+  return { rung: start.rung, ladder: kept.map((x) => x.rung), ...(tie ? { tie } : {}) };
+}
+
 /**
- * The role's default rung and every candidate above it (the whole list when it has no default), in cost
- * order under either objective: speed order would put slower, not stronger, rungs above the default.
+ * The role's default rung and every candidate at least as strong on every dimension it has a value on (the
+ * whole list when it has no default), in cost order under either objective: speed order would put slower, not
+ * stronger, rungs above the default.
  */
 export function defaultLadder(c: Catalog, p: RoutingProfile, role: Role): Pick {
-  const all = candidates(c, { ...p, objective: "cost" }, role).map((x) => x.rung);
+  const all = candidates(c, { ...p, objective: "cost" }, role);
   if (all.length === 0) throw noRung(role);
-  const i = Math.max(0, all.indexOf(p.role.defaultRung ?? ""));
-  return { rung: all[i] as string, ladder: all.slice(i) };
+  const start = all.find((x) => x.rung === p.role.defaultRung) ?? (all[0] as Candidate);
+  return ladderFrom(start, all, compareDims(start, {}), p.usage);
 }
 
 /**
@@ -108,29 +203,86 @@ export function defaultDifficulty(c: Catalog, p: RoutingProfile, role: Role, kin
   return cleared.at(-1) ?? "build";
 }
 
+/** The kind's main dimension: what a speed ladder sorts on and what `best is` reads first. */
+export const primaryDim = (kind: Kind): Dim =>
+  kind === "terminal" ? "terminal" : kind === "ui" ? "frontend" : "repo_code";
+
 /**
  * Under `objective: "speed"` the objective picks only the start (the fastest bar-clearing rung); the
- * ladder above it is the other bar-clearing rungs at least as strong on the kind's primary dimension,
- * weakest first, cost breaking ties, so a lane never climbs onto a weaker rung. Ported from 0.x.
+ * ladder above it is the other rungs at least as strong on the bar, weakest first on the kind's primary
+ * dimension, cost breaking ties, so a lane never climbs onto a weaker rung. Ported from 0.x.
  */
-function speedLadder(clearing: Candidate[], kind: Kind): Pick {
-  const start = clearing[0] as Candidate;
-  const dim: Dim = kind === "terminal" ? "terminal" : "repo_code";
+function speedLadder(start: Candidate, all: Candidate[], kind: Kind, dims: Dim[], p: RoutingProfile): Pick {
+  const dim = primaryDim(kind);
   const strength = (x: Candidate) => x.scores[dim] ?? Number.NEGATIVE_INFINITY;
-  const rest = clearing
-    .filter((x) => x !== start && strength(x) >= strength(start))
-    .sort((a, b) => strength(a) - strength(b) || compareCost(a.cost, b.cost));
-  return { rung: start.rung, ladder: [start, ...rest].map((x) => x.rung) };
+  const order = [...all].sort((a, b) => strength(a) - strength(b) || compareCost(a.cost, b.cost));
+  return ladderFrom(start, order, dims, p.usage);
+}
+
+/** The thresholds of `bar` a rung misses, each with its value: `agentic 0.0818 < 0.1077`. */
+function shortfalls(cand: Candidate, bar: Partial<Record<Dim, number>>): string[] {
+  return (Object.entries(bar) as [Dim, number | undefined][]).flatMap(([dim, min]) => {
+    if (min === undefined) return [];
+    const v = cand.scores[dim];
+    return v !== undefined && v >= min ? [] : [`${dim} ${v ?? "none"} < ${min}`];
+  });
+}
+
+/**
+ * Spec 1.5 plan 24: when no rung clears a bar, the one closest to it: the fewest thresholds missed, then the
+ * highest on the kind's primary dimension, then the candidates' order.
+ */
+function bestOf(all: Candidate[], bar: Partial<Record<Dim, number>>, kind: Kind): Candidate {
+  const dim = primaryDim(kind);
+  const v = (x: Candidate) => x.scores[dim] ?? Number.NEGATIVE_INFINITY;
+  const misses = (x: Candidate) => shortfalls(x, bar).length;
+  return [...all].sort((a, b) => misses(a) - misses(b) || v(b) - v(a))[0] as Candidate;
 }
 
-/** Spec §5.4: the start rung and ladder for a lane of this kind and difficulty (0.x `select`). */
+/** `no rung clears repo_code/hard; best is codex:gpt-6-sol#xhigh (agentic 0.0818 < 0.1077)`. */
+export function noClearLine(
+  all: Candidate[],
+  bar: Partial<Record<Dim, number>>,
+  kind: Kind,
+  d: Difficulty,
+): string {
+  const best = bestOf(all, bar, kind);
+  return `no rung clears ${kind}/${d}; best is ${best.rung} (${shortfalls(best, bar).join(", ")})`;
+}
+
+/**
+ * Spec §5.4: the start rung and ladder for a lane of this kind and difficulty (0.x `select`). The start is the
+ * first rung in objective order that clears the bar. When none does, it is the default rung, raised to an
+ * easier difficulty's start when that one scores at least the default on this bar (spec 1.5 plan 24: `logic`
+ * starts no lower than `build`), and `noClear` says so. The ladder above the start only goes up.
+ */
 export function select(c: Catalog, p: RoutingProfile, role: Role, kind: Kind, difficulty: Difficulty): Pick {
   const all = candidates(c, p, role, kind);
   if (all.length === 0) throw noRung(role);
-  if (all.length === 1) return { rung: all[0]?.rung as string, ladder: [all[0]?.rung as string] };
-  const clearing = all.filter((x) => clearsBar(c, x, kind, difficulty));
-  if (clearing.length === 0) return defaultLadder(c, p, role);
-  return p.objective === "speed"
-    ? speedLadder(clearing, kind)
-    : { rung: clearing[0]?.rung as string, ladder: clearing.map((x) => x.rung) };
+  const bar = c.bars[kind][difficulty];
+  if (all.length === 1) {
+    const only = all[0] as Candidate;
+    const one = { rung: only.rung, ladder: [only.rung] };
+    return clearsBar(c, only, kind, difficulty)
+      ? one
+      : { ...one, noClear: noClearLine(all, bar, kind, difficulty) };
+  }
+  const first = all.find((x) => clearsBar(c, x, kind, difficulty));
+  if (first) {
+    const dims = compareDims(first, bar);
+    return p.objective === "speed"
+      ? speedLadder(first, all, kind, dims, p)
+      : ladderFrom(first, all, dims, p.usage);
+  }
+  const byCost = candidates(c, { ...p, objective: "cost" }, role, kind);
+  const fallback = defaultLadder(c, p, role).rung;
+  let start = byCost.find((x) => x.rung === fallback) ?? (byCost[0] as Candidate);
+  const dims = compareDims(start, bar);
+  for (const easier of DIFFICULTIES.slice(0, DIFFICULTIES.indexOf(difficulty)).reverse()) {
+    const s = byCost.find((x) => clearsBar(c, x, kind, easier));
+    if (!s) continue;
+    if (atLeast(s, start, dims)) start = s;
+    break;
+  }
+  return { ...ladderFrom(start, byCost, dims, p.usage), noClear: noClearLine(all, bar, kind, difficulty) };
 }

package/src/domain/state.ts

@@ -16,6 +16,8 @@ export interface StateView {
   dirty: { path: string; owner: string | null }[];
   running: { name: string; rung: string; thread: string | null; since: string; brief: string }[];
   lastCheck: string | null;
+  /** spec 1.5 "Pinned per run": what changed since the pin; dispatch keeps the pinned values */
+  pinChanges?: string[];
   next: string;
   /** spec 1.1 §10: the protocol's next step, derived from the run's files; always the last line */
   protocol: string;
@@ -40,6 +42,9 @@ export function renderState(s: StateView): string {
       : ["- none"]),
     "",
     `Last check: ${s.lastCheck ?? "none"}`,
+    ...(s.pinChanges?.length
+      ? [`Pinned: ${s.pinChanges.join("; ")} (dispatch keeps the pinned values; run_pin re-pins)`]
+      : []),
     "",
     // 1.1: no tool waits; each running role's record arrives as a catherd message
     `Next: ${waiting.length ? `running ${waiting.join(", ")} (results arrive as catherd messages; peek to check); then ${s.next}` : s.next}`,

package/src/domain/util.ts

@@ -16,6 +16,28 @@ export function median(xs: readonly number[]): number | null {
   return s.length % 2 ? (s[m] as number) : ((s[m - 1] as number) + (s[m] as number)) / 2;
 }
 
+/** A stretch of time in epoch ms; `to` null while it is still open. */
+export interface Span {
+  from: number;
+  to: number | null;
+}
+
+/** How many ms of [from, to] any of `spans` covers, overlaps counted once; an open span runs to `to`. */
+export function coveredMs(from: number, to: number, spans: readonly Span[]): number {
+  const clipped = spans
+    .map((s) => [Math.max(from, s.from), Math.min(to, s.to ?? to)] as const)
+    .filter(([a, b]) => b > a)
+    .sort((x, y) => x[0] - y[0]);
+  let total = 0;
+  let end = -Infinity;
+  for (const [a, b] of clipped) {
+    if (b <= end) continue;
+    total += b - Math.max(a, end);
+    end = b;
+  }
+  return total;
+}
+
 /** A plain object: not null and not an array. */
 export const isPlain = (v: unknown): v is Record<string, unknown> =>
   typeof v === "object" && v !== null && !Array.isArray(v);

package/src/domain/workspace.ts

@@ -0,0 +1,130 @@
+import { z } from "zod";
+import { ID_PATTERN } from "./ids.ts";
+
+export const WORKSPACE_LIMIT = 100;
+
+export const WorkspaceIdSchema = z
+  .string()
+  .regex(ID_PATTERN)
+  .refine((s) => !s.includes(".."));
+export const WorkspaceBudgetSchema = z.strictObject({
+  minutes: z.number().finite().nonnegative().optional(),
+  tokens: z.number().finite().nonnegative().optional(),
+  usd: z.number().finite().nonnegative().optional(),
+});
+/** A git ref a release waits on (`origin/main`): no option, no range, no whitespace. */
+export const BaseRefSchema = z
+  .string()
+  .regex(/^[A-Za-z0-9_][A-Za-z0-9._/-]*$/)
+  .refine((s) => !s.includes("..") && !s.endsWith("/") && !s.endsWith(".lock"));
+export const RELEASES = ["land", "merge"] as const;
+export const WorkspaceStepSchema = z
+  .strictObject({
+    id: WorkspaceIdSchema,
+    repo: WorkspaceIdSchema,
+    title: z.string().min(1),
+    aLines: z.array(z.string()),
+    dependsOn: z.array(WorkspaceIdSchema).max(WORKSPACE_LIMIT).default([]),
+    milestone: WorkspaceIdSchema.default("M1"),
+    /**
+     * When the step releases its dependents: once its milestone lands (the default), or once the landed
+     * commit is an ancestor of `base` in its repository (`git merge-base --is-ancestor`), checked when a
+     * dependent asks, never polled.
+     */
+    release: z.enum(RELEASES).default("land"),
+    base: BaseRefSchema.optional(),
+  })
+  .refine((s) => (s.release === "merge") === (s.base !== undefined), {
+    message: 'release "merge" needs a base ref (e.g. origin/main), and only it takes one',
+  });
+export type WorkspaceStep = z.infer<typeof WorkspaceStepSchema>;
+export const WorkspaceSchema = z
+  .strictObject({
+    schema: z.literal(1),
+    id: WorkspaceIdSchema,
+    root: z.string().min(1),
+    title: z.string().min(1),
+    aLines: z.array(z.string()),
+    createdAt: z.iso.datetime(),
+    budget: WorkspaceBudgetSchema,
+    repos: z
+      .record(WorkspaceIdSchema, z.string().min(1))
+      .refine((repos) => Object.keys(repos).length <= WORKSPACE_LIMIT),
+    steps: z.array(WorkspaceStepSchema).min(1).max(WORKSPACE_LIMIT),
+  })
+  .superRefine((workspace, ctx) => {
+    // Zod may still refine an oversized array; do not traverse invalid graphs.
+    if (
+      workspace.steps.length > WORKSPACE_LIMIT ||
+      Object.keys(workspace.repos).length > WORKSPACE_LIMIT ||
+      workspace.steps.some((step) => step.dependsOn.length > WORKSPACE_LIMIT)
+    )
+      return;
+    const ids = new Set<string>();
+    let invalidIdentity = false;
+    for (const step of workspace.steps) {
+      if (ids.has(step.id) || !Object.hasOwn(workspace.repos, step.repo)) {
+        invalidIdentity = true;
+        ctx.addIssue({
+          code: "custom",
+          message: "steps require unique ids and repositories present in the snapshot",
+        });
+      }
+      ids.add(step.id);
+    }
+    if (invalidIdentity) return;
+    const byId = new Map(workspace.steps.map((step) => [step.id, step]));
+    const remaining = new Map<string, number>();
+    const dependents = new Map<string, string[]>();
+    const ready: string[] = [];
+    for (const step of workspace.steps) {
+      if (
+        new Set(step.dependsOn).size !== step.dependsOn.length ||
+        step.dependsOn.some((id) => !byId.has(id))
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          message: "dependencies must form a graph without cycles or unknown steps",
+        });
+        return;
+      }
+      remaining.set(step.id, step.dependsOn.length);
+      if (!step.dependsOn.length) ready.push(step.id);
+      for (const id of step.dependsOn) {
+        const next = dependents.get(id) ?? [];
+        next.push(step.id);
+        dependents.set(id, next);
+      }
+    }
+    const ancestors = new Map<string, Set<string>>();
+    const latestByRepo = new Map<string, string>();
+    // Topological order makes adjacent owners sufficient: if each owner follows
+    // the previous owner transitively, every pair of owners is ordered.
+    for (let i = 0; i < ready.length; i++) {
+      const step = byId.get(ready[i]!)!;
+      const before = new Set<string>();
+      for (const id of step.dependsOn) {
+        before.add(id);
+        for (const ancestor of ancestors.get(id)!) before.add(ancestor);
+      }
+      ancestors.set(step.id, before);
+      const previous = latestByRepo.get(step.repo);
+      if (previous && !before.has(previous))
+        ctx.addIssue({
+          code: "custom",
+          message: "steps sharing a repository must be ordered by dependencies",
+        });
+      latestByRepo.set(step.repo, step.id);
+      for (const id of dependents.get(step.id) ?? []) {
+        const count = remaining.get(id)! - 1;
+        remaining.set(id, count);
+        if (!count) ready.push(id);
+      }
+    }
+    if (ready.length !== workspace.steps.length)
+      ctx.addIssue({
+        code: "custom",
+        message: "dependencies must form a graph without cycles or unknown steps",
+      });
+  });
+export type Workspace = z.infer<typeof WorkspaceSchema>;

package/src/entry/catalog-command.ts

@@ -1,3 +1,4 @@
+import { HOST_ARG, terminalHost } from "./host-arg.ts";
 import { defineCommand } from "citty";
 import { CatherdError, isCatherdError } from "../domain/errors.ts";
 import { ROLES, type Role } from "../domain/roles.ts";
@@ -12,7 +13,7 @@ import {
 import { readDerived } from "../infra/sources/cache.ts";
 import { type SyncReport, syncSources } from "../services/source-sync.ts";
 import { clearTreatLike, type LeftOnStandIn, resetTreatLikes, suggestFor } from "../services/treat-likes.ts";
-import { exitCodeOf, JSON_ARG, mark, printError } from "./cli-kit.ts";
+import { exitCodeOf, JSON_ARG, mark, printError, refuseInRole } from "./cli-kit.ts";
 
 /**
  * Spec 1.2 §9: a sync, one line per source (fetched, fresh, skipped, or failed with the answer it kept),
@@ -98,7 +99,7 @@ export function formatModel(m: CatalogModel): string {
     // spec 1.2 §5.3: each value with its confidence and source, as `route` reports it; a guess names its rung
     const values = Object.entries(r.scores).map(
       ([dim, v]) =>
-        `${dim} ${Number(v.value.toPrecision(4))} (${v.from ? `inferred from ${v.from}` : v.confidence}, ${v.source})`,
+        `${dim} ${Number(v.value.toPrecision(4))} (${v.from ? (v.lent === "treat-like" ? `like ${v.from}` : `inferred from ${v.from}`) : v.confidence}, ${v.source})`,
     );
     if (values.length === 0 && !r.evidence) continue;
     lines.push(`  #${r.rung.slice(r.rung.lastIndexOf("#") + 1)}  ${values.join(" · ") || "unscored"}`);
@@ -162,10 +163,17 @@ const list = defineCommand({
 
 /** Spec 1.2 §6.4: the profile rungs a removal leaves on an inferred stand-in or unscored, one line each. */
 export function leftLines(left: LeftOnStandIn[], plain = false): string[] {
-  return left.map(
-    (l) =>
-      `${mark("warn", plain)} ${l.profile}: ${l.rung} is left ${l.unscored ? "unscored: routing skips it" : `on an inferred stand-in for ${l.dims.join(", ")}`}`,
-  );
+  return left.map((l) => {
+    const what = l.unscored
+      ? ["unscored: routing skips it"]
+      : [
+          ...(l.dims.length ? [`on an inferred stand-in for ${l.dims.join(", ")}`] : []),
+          ...(l.missing?.length
+            ? [`with no ${l.missing.join(", ")} value: it clears no bar that needs one`]
+            : []),
+        ];
+    return `${mark("warn", plain)} ${l.profile}: ${l.rung} is left ${what.join(", and ")}`;
+  });
 }
 
 /** Spec 1.2 §6.4 `--suggest`: the three nearest stand-ins, each with its distance and the features it rests on. */
@@ -194,6 +202,7 @@ const treatLike = defineCommand({
       "Score an unscored rung as a scored one; --suggest ranks stand-ins, --clear and --reset remove your mappings",
   },
   args: {
+    ...HOST_ARG,
     rung: {
       type: "positional",
       required: false,
@@ -227,15 +236,16 @@ const treatLike = defineCommand({
         else for (const l of suggestLines(r, args.suggest)) console.log(l);
         return;
       }
+      refuseInRole(process.env, "catherd catalog treat-like");
       if (args.clear !== undefined) {
-        const r = await clearTreatLike(args.clear);
+        const r = await clearTreatLike(args.clear, terminalHost(args.host).host);
         if (args.json) return console.log(JSON.stringify(r, null, 2));
         for (const l of leftLines(r.left)) console.log(l);
         console.log(`${mark("ok")} ${r.rung} is no longer treated like ${r.like}`);
         return;
       }
       if (args.reset) {
-        const r = await resetTreatLikes();
+        const r = await resetTreatLikes(terminalHost(args.host).host);
         if (args.json) return console.log(JSON.stringify(r, null, 2));
         for (const l of leftLines(r.left)) console.log(l);
         console.log(

package/src/entry/cli-kit.ts

@@ -1,4 +1,5 @@
-import { type CatherdError, isCatherdError } from "../domain/errors.ts";
+import { CatherdError, isCatherdError } from "../domain/errors.ts";
+import { roleScopeFromEnv } from "../domain/role-scope.ts";
 import { RUN_NOT_FOUND_FIX } from "../services/run-store.ts";
 import { glyph, type State } from "./glyphs.ts";
 
@@ -24,6 +25,21 @@ export function printError(e: Pick<CatherdError, "code" | "message" | "fix">): v
 export const exitCodeOf = (e: unknown): number =>
   isCatherdError(e) && e.code === "E_INPUT_INVALID" ? EXIT.usage : EXIT.error;
 
+/**
+ * Spec 1.5 plan 21: a role's shell (CATHERD_ROLE, or its scratch TMPDIR) never runs a command that writes the
+ * orchestrator's state (pause, runs cancel, profile set, …): E_ROLE_SCOPE, as `catherd run-file` and `catherd gate`
+ * refuse an operation the role has not. `command` is the command as typed, like `catherd pause`.
+ */
+export function refuseInRole(env: Record<string, string | undefined>, command: string): void {
+  const scope = roleScopeFromEnv(env);
+  if (!scope) return;
+  throw new CatherdError(
+    "E_ROLE_SCOPE",
+    `${command} is the orchestrator's: this process runs ${scope.name} of run ${scope.run}`,
+    { fix: "report it in your reply; the orchestrator does it" },
+  );
+}
+
 export const printJson = (v: unknown): void => console.log(JSON.stringify(v, null, 2));
 
 /** The `--json` flag every read command takes. */

package/src/entry/deps.ts

@@ -1,3 +1,5 @@
+import type { HostContext } from "../domain/host.ts";
+import { roleScopeFromEnv } from "../domain/role-scope.ts";
 import { readSessionEnv } from "../infra/claude-session.ts";
 import { VERSION } from "../infra/version.ts";
 import type { Deps } from "../services/ports.ts";
@@ -5,13 +7,16 @@ import { profileService } from "../services/profile-service.ts";
 import { routingService } from "../services/routing-service.ts";
 
 /** The services every entry point (MCP server, CLI commands) runs on. */
-export function defaultDeps(): Deps {
-  return {
-    profiles: profileService(),
+export function defaultDeps(host: HostContext = { host: "unknown", session: null, conflict: null }): Deps {
+  const deps: Deps = {
+    host,
+    profiles: profileService(() => deps.host),
     routing: routingService(),
     version: VERSION,
     pollMs: 250,
     session: readSessionEnv(process.env),
     now: Date.now,
+    role: roleScopeFromEnv(process.env),
   };
+  return deps;
 }

package/src/entry/doctor-command.ts

@@ -1,10 +1,13 @@
+import { gitToplevel } from "../infra/git.ts";
+import { CatherdError } from "../domain/errors.ts";
+import { HOST_ARG, terminalHost, withThread } from "./host-arg.ts";
 import { defineCommand } from "citty";
 import { VERSION } from "../infra/version.ts";
 import { type DoctorReport, doctor } from "../services/doctor.ts";
-import { probePush } from "../services/doctor-push.ts";
 import type { Check } from "../services/doctor-checks.ts";
 import { EXIT, JSON_ARG, mark, printJson } from "./cli-kit.ts";
 import { mcpHandshake } from "./mcp/handshake.ts";
+import { probeRoleServer } from "../infra/role-mcp.ts";
 
 /**
  * One row per check: `✓ ready  Bun — 1.4.2`, then the full fix on its own line; a fix of several lines
@@ -34,15 +37,39 @@ export const doctorCommand = defineCommand({
     description: "Readiness report: Bun, backends, Jev, the plugin, agents, the MCP server, locks",
   },
   args: {
+    ...HOST_ARG,
     ...JSON_ARG,
+    "test-push": {
+      type: "boolean",
+      description:
+        "send one labeled smoke to the validated original session (receipt does not prove processing)",
+    },
+    thread: {
+      type: "string",
+      description:
+        "with --test-push: the Codex thread to send the smoke to (Codex does not export it to the commands it runs)",
+    },
+    docker: {
+      type: "boolean",
+      description:
+        "also probe Docker as a gate sees it: two compose services reaching each other by name, and the free disk (pulls busybox)",
+    },
     plain: { type: "boolean", description: "ASCII glyphs (NO_COLOR drops only colour)" },
   },
   async run({ args }) {
+    if (args.thread !== undefined && args["test-push"] !== true)
+      throw new CatherdError("E_INPUT_INVALID", "--thread only names where --test-push sends its smoke", {
+        fix: `catherd doctor --test-push --thread ${args.thread}`,
+      });
     const r = await doctor({
+      host: withThread(terminalHost(args.host), args.thread),
+      repo: await gitToplevel(process.cwd()),
       bunVersion: Bun.version,
       version: VERSION,
       handshake: () => mcpHandshake(),
-      push: () => probePush(),
+      roleServerStart: () => probeRoleServer(),
+      testPush: args["test-push"] === true,
+      docker: args.docker === true,
     });
     if (args.json) printJson(r);
     else for (const l of formatReport(r, args.plain === true)) console.log(l);