catherd-cli 0.2.1 → 1.1.0

package/src/services/global-install.ts

@@ -0,0 +1,99 @@
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { errorMessage } from "../domain/errors.ts";
+import { scrubSecrets } from "../infra/env.ts";
+
+/** How `init` finds and installs the global `catherd` (injectable: tests never reach the registry). */
+export interface GlobalInstallDeps {
+  /**
+   * what the `catherd` in bun's global bin prints for --version; null when there is none or it does not
+   * answer. Never PATH: under `bunx catherd-cli init`, PATH first finds bunx's own transient shim.
+   */
+  globalVersion(): Promise<string | null>;
+  /** what the first `catherd` on PATH outside a bunx transient install prints for --version, or null */
+  pathVersion(): Promise<string | null>;
+  /** `bun add -g catherd-cli@<version>`, with its output */
+  install(version: string): Promise<{ ok: boolean; output: string }>;
+}
+
+export type GlobalInstall =
+  | { state: "current" }
+  | { state: "installed" }
+  /** installed, but the `catherd` first on PATH is another version (or none), so the launcher still runs bunx */
+  | { state: "shadowed"; onPath: string | null }
+  | { state: "failed"; reason: string };
+
+async function run(cmd: string[]): Promise<{ ok: boolean; stdout: string; output: string }> {
+  const p = Bun.spawn(cmd, {
+    env: scrubSecrets(process.env),
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [out, err, code] = await Promise.all([
+    new Response(p.stdout).text(),
+    new Response(p.stderr).text(),
+    p.exited,
+  ]);
+  return { ok: code === 0, stdout: out, output: `${err}${out}` };
+}
+
+/** what `bin --version` prints on stdout (a warning on stderr must not make it look like another version) */
+async function versionOf(bin: string | null): Promise<string | null> {
+  if (!bin) return null;
+  const r = await run([bin, "--version"]).catch(() => null);
+  return r?.ok ? r.stdout.trim() || null : null;
+}
+
+/**
+ * bun's global bin folder: `bun pm bin -g`, else where bun puts it by default. `bun pm bin -g` fails
+ * (Bun 1.4.2) while the global folder exists without a package.json, which is before the first global install.
+ */
+async function globalBin(): Promise<string> {
+  const r = await run([process.execPath, "pm", "bin", "-g"]).catch(() => null);
+  const dir = r?.ok ? r.stdout.trim() : "";
+  if (dir) return dir;
+  return process.env.BUN_INSTALL_BIN || join(process.env.BUN_INSTALL || join(homedir(), ".bun"), "bin");
+}
+
+/** `bunx` runs a package from `<tmp>/bunx-<uid>-<package>@<tag>/node_modules/.bin`, prepended to PATH */
+const isBunxBin = (dir: string) => dir.split(/[\\/]/).some((part) => part.startsWith("bunx-"));
+
+export const realGlobalInstall: GlobalInstallDeps = {
+  async globalVersion() {
+    return versionOf(Bun.which("catherd", { PATH: await globalBin() }));
+  },
+  async pathVersion() {
+    const PATH = (process.env.PATH ?? "")
+      .split(delimiter)
+      .filter((dir) => dir && !isBunxBin(dir))
+      .join(delimiter);
+    return versionOf(Bun.which("catherd", { PATH }));
+  },
+  install: (version) =>
+    run([process.execPath, "add", "-g", `catherd-cli@${version}`]).catch((e: unknown) => ({
+      ok: false,
+      output: errorMessage(e),
+    })),
+};
+
+/**
+ * Spec 1.1 §12: the global CLI at `version`, so the plugin's launcher starts it without a bunx resolve.
+ * `installing` runs before anything is resolved, so the user sees why the next seconds pass.
+ */
+export async function ensureGlobal(
+  version: string,
+  deps: GlobalInstallDeps,
+  installing: () => void,
+): Promise<GlobalInstall> {
+  if ((await deps.globalVersion()) === version) return { state: "current" };
+  installing();
+  // never rejects: a failed install is reported, and init goes on
+  const r = await deps.install(version).catch((e: unknown) => ({ ok: false, output: errorMessage(e) }));
+  if (r.ok) {
+    const onPath = await deps.pathVersion().catch(() => null);
+    return onPath === version ? { state: "installed" } : { state: "shadowed", onPath };
+  }
+  const reason = r.output.split("\n").find((l) => l.trim()) ?? "bun add -g failed";
+  return { state: "failed", reason: reason.trim() };
+}

package/src/services/jev-service.ts

@@ -0,0 +1,183 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { CatherdError, isCatherdError } from "../domain/errors.ts";
+import type { RouteSource } from "../domain/route.ts";
+import {
+  canonicalJson,
+  type JevAnswers,
+  type JevFile,
+  JevFileSchema,
+  parseReply,
+  questionSetId,
+  requestKey,
+  type SetName,
+  sha256,
+} from "../domain/jev.ts";
+import { assetPath } from "../infra/assets.ts";
+import { type JevTransport, jevRequest } from "../infra/jev-client.ts";
+import { addSecret, log } from "../infra/log.ts";
+import { configDir } from "../infra/paths.ts";
+import { appendJsonl, ensureJsonlHeader, readJsonl, readVersioned, writeJsonAtomic } from "../infra/store.ts";
+
+let file: JevFile | null = null;
+/** catalog/jev.json: the question sets and their rules (spec §5.5). */
+export const jevQuestions = (): JevFile =>
+  (file ??= readVersioned(assetPath("catalog/jev.json"), JevFileSchema, 1));
+
+export const credentialsPath = (): string => join(configDir(), "credentials.json");
+const CredentialsSchema = z.looseObject({
+  schema: z.literal(1).default(1),
+  typesafeApiKey: z.string().optional(),
+});
+
+/** Registers the saved Jev key with the redactor, for a process that reads logs without ever calling Jev. */
+export function registerSavedSecrets(): void {
+  addSecret(jevKey());
+}
+
+/** How to repair a credentials file catherd cannot read: `init` alone refuses to overwrite it. */
+const credentialsFix = (): string =>
+  `delete ${credentialsPath()} and run catherd init, or write it as {"schema": 1, "typesafeApiKey": "<your key>"}`;
+const readCredentials = () =>
+  readVersioned(credentialsPath(), CredentialsSchema, 1, { fix: credentialsFix() });
+
+/** The key saved in credentials.json, or why that file cannot be read (unparsable, newer schema). */
+export function savedJevKey(): { key: string | null; problem: CatherdError | null } {
+  if (!existsSync(credentialsPath())) return { key: null, problem: null };
+  try {
+    return { key: readCredentials().typesafeApiKey?.trim() || null, problem: null };
+  } catch (e) {
+    return {
+      key: null,
+      problem: isCatherdError(e)
+        ? e
+        : new CatherdError("E_CONFIG_INVALID", String(e), { fix: credentialsFix() }),
+    };
+  }
+}
+
+/**
+ * Spec §5.5: `TYPESAFE_API_KEY`, else `<config>/credentials.json`; null when neither has one. Jev is
+ * optional (D1), so a credentials file that cannot be read means no key here; it is logged, and
+ * `catherd doctor` says why.
+ */
+export function jevKey(): string | null {
+  const env = process.env.TYPESAFE_API_KEY?.trim();
+  if (env) return env;
+  const { key, problem } = savedJevKey();
+  if (problem) log("warn", "jev", { error: `no key: ${problem.message}` });
+  return key;
+}
+
+/**
+ * Keeps any other credential, and the file at mode 600 (spec §10.4). A missing file starts empty; an
+ * unreadable or newer-schema one is refused (it throws) rather than overwritten.
+ */
+export function saveJevKey(key: string): void {
+  const cur: z.infer<typeof CredentialsSchema> = existsSync(credentialsPath())
+    ? readCredentials()
+    : { schema: 1 };
+  writeJsonAtomic(credentialsPath(), { ...cur, schema: 1, typesafeApiKey: key.trim() }, { mode: 0o600 });
+}
+
+/** A key works when Jev lists its models: no inference, and no dependence on a question set. */
+export async function testJevKey(key: string, o: JevTransport = {}): Promise<boolean> {
+  return (await jevRequest("GET", "/models", key, undefined, o)).ok;
+}
+
+export interface JevOpts extends JevTransport {
+  /** a key to use instead of jevKey(); null means none */
+  key?: string | null;
+}
+
+/** One jev.jsonl row (spec §5.5): never the state, only its hash. */
+export interface JevRow {
+  at: string;
+  call: SetName;
+  lane: string | null;
+  questionSet: string;
+  key: string;
+  stateHash: string;
+  model: string | null;
+  requestId: string | null;
+  usage: { input_tokens: number; output_tokens: number } | null;
+  latencyMs: number | null;
+  attempts: number;
+  cached: boolean;
+  answers: JevAnswers | null;
+  derived: Record<string, unknown> | null;
+  used: string;
+  source: RouteSource;
+  why: string;
+}
+
+export interface Asked {
+  answers: JevAnswers | null;
+  /** why Jev gave no answers ("no key", "http 401", …), or a note on answers from an unpinned model */
+  why: string | null;
+  meta: Omit<JevRow, "at" | "answers" | "derived" | "used" | "source" | "why" | "call" | "lane">;
+}
+
+const jevLog = (runDir: string) => join(runDir, "jev.jsonl");
+
+export function logJev(runDir: string, row: Omit<JevRow, "at">): void {
+  const f = jevLog(runDir);
+  ensureJsonlHeader(f, "jev");
+  appendJsonl(f, { at: new Date().toISOString(), ...row });
+}
+
+/**
+ * Asks one question set about `state`. A request this run already had answered (same model, state and
+ * questions) is answered from jev.jsonl, so a re-routed lane gets the same decision.
+ */
+export async function askJev(runDir: string, set: SetName, state: unknown, o: JevOpts = {}): Promise<Asked> {
+  const f = jevQuestions();
+  const questions = f.sets[set].questions;
+  const key = requestKey(f.model, state, questions);
+  const meta: Asked["meta"] = {
+    questionSet: questionSetId(f, set),
+    key,
+    stateHash: sha256(canonicalJson(state)),
+    model: null,
+    requestId: null,
+    usage: null,
+    latencyMs: null,
+    attempts: 0,
+    cached: false,
+  };
+  // a logged answer is checked like a fresh one: a row edited by hand, or cut short, is asked again
+  for (const hit of readJsonl<Partial<JevRow>>(jevLog(runDir)).rows) {
+    if (hit.key !== key || !hit.answers) continue;
+    const cached = parseReply(questions, { model: hit.model ?? "", answers: hit.answers });
+    if (!cached.ok) continue;
+    const model = hit.model ?? null;
+    return { answers: cached.answers, why: drift(model, f.model), meta: { ...meta, model, cached: true } };
+  }
+  const apiKey = o.key === undefined ? jevKey() : o.key;
+  if (!apiKey) return { answers: null, why: "no key", meta };
+  addSecret(apiKey);
+  const res = await jevRequest("POST", "/systemone", apiKey, { model: f.model, state, questions }, o);
+  log(res.ok ? "info" : "warn", "jev", {
+    set,
+    questionSet: meta.questionSet,
+    stateHash: meta.stateHash,
+    requestId: res.ok ? res.requestId : null,
+    latencyMs: res.latencyMs,
+    attempts: res.attempts,
+    ...(res.ok ? {} : { error: res.error }),
+  });
+  meta.latencyMs = res.latencyMs;
+  meta.attempts = res.attempts;
+  if (!res.ok) return { answers: null, why: res.error, meta };
+  meta.requestId = res.requestId;
+  const parsed = parseReply(questions, res.body);
+  if (!parsed.ok) return { answers: null, why: parsed.error, meta };
+  meta.model = parsed.model;
+  meta.usage = parsed.usage;
+  return { answers: parsed.answers, why: drift(parsed.model, f.model), meta };
+}
+
+/** The note on answers from a model other than the pinned one, or null. */
+const drift = (model: string | null, pinned: string): string | null =>
+  model === null || model === pinned ? null : `answered by ${model}, not the pinned ${pinned}`;

package/src/services/lane-service.ts

@@ -0,0 +1,390 @@
+import { existsSync, readFileSync } from "node:fs";
+import { relative, sep } from "node:path";
+import { CatherdError } from "../domain/errors.ts";
+import { assertId, ID_PATTERN, parseRung } from "../domain/ids.ts";
+import { assertLaneHeader, type Difficulty, type Kind } from "../domain/lane.ts";
+import type { Role } from "../domain/roles.ts";
+import {
+  type ClimbReason,
+  currentRoute,
+  laneOutcome,
+  nextRung,
+  type RouteJev,
+  type RouteSource,
+} from "../domain/route.ts";
+import { withFileLock } from "../infra/filelock.ts";
+import { commitExists } from "../infra/git.ts";
+import { laneFile } from "./admission.ts";
+import { budgetOf } from "./budget.ts";
+import {
+  isDocPath,
+  isSourcePath,
+  landedMilestones,
+  fullCommit,
+  milestoneFiles,
+  milestoneStart,
+  reviewerPassed,
+  milestoneVerifier,
+} from "./milestones.ts";
+import type { Deps, Verdict } from "./ports.ts";
+import {
+  appendLedger,
+  appendOutcome,
+  appendRoute,
+  findRun,
+  knowledgeFile,
+  readRoutes,
+  type Run,
+  runFile,
+  runPaths,
+} from "./run-store.ts";
+import { writeDigest } from "./protocol.ts";
+import { openQuestions } from "./questions.ts";
+import { type Notes, type NotesPatch, refreshState } from "./state.ts";
+import { appendPrivate } from "../infra/store.ts";
+
+const withHints = (hints: string[]) => (hints.length ? { hints } : {});
+
+export interface RouteResult {
+  lane: string | null;
+  role: Role;
+  rung: string;
+  ladder: string[];
+  source: RouteSource;
+  kind: Kind | null;
+  difficulty: Difficulty | null;
+  backend: string;
+  /** the native agent to run a `claude:` rung as */
+  agent: string | null;
+  /** the Jev question set asked, and what it said, when Jev was asked */
+  questionSet: string | null;
+  jev: RouteJev | null;
+}
+
+function readLaneFile(run: Run, path: string): { lane: string; text: string } {
+  const file = runFile(run, path, "read");
+  const [folder, name, ...deeper] = relative(run.dir, file).split(sep);
+  const lane = folder === "lanes" && deeper.length === 0 && name?.endsWith(".md") ? name.slice(0, -3) : null;
+  if (!lane || !ID_PATTERN.test(lane))
+    throw new CatherdError("E_LANE_INVALID", `a lane file lives at lanes/<id>.md, not ${path}`, {
+      fix: "pass lane_file as lanes/Mx.Ly.md",
+    });
+  if (!existsSync(file))
+    throw new CatherdError("E_LANE_INVALID", `no lane file ${path}`, {
+      fix: "write it with write_run_file first",
+    });
+  const text = readFileSync(file, "utf8");
+  // spec 1.1 §6: a lane routes only on values the catalog knows
+  assertLaneHeader(text, `lanes/${lane}.md`);
+  return { lane, text };
+}
+
+/** Spec §5.4 through the routing port; a lane's route is recorded in routes.jsonl. */
+export async function route(
+  deps: Deps,
+  i: { run: string; laneFile?: string; role: Role },
+): Promise<RouteResult> {
+  const run = findRun(i.run);
+  const lane = i.laneFile === undefined ? null : readLaneFile(run, i.laneFile);
+  const profile = deps.profiles.forRepo(run.meta.repo);
+  const a = await deps.routing.route({
+    runDir: run.dir,
+    repo: run.meta.repo,
+    profile,
+    role: i.role,
+    lane: lane?.lane ?? null,
+    laneText: lane?.text ?? null,
+    spentFraction: budgetOf(run, profile.budget, deps.now())?.fraction ?? 0,
+  });
+  if (lane)
+    appendRoute(run, {
+      at: new Date(deps.now()).toISOString(),
+      lane: lane.lane,
+      role: i.role,
+      rung: a.rung,
+      ladder: a.ladder,
+      source: "route",
+      decidedBy: a.source,
+      from: null,
+      reason: null,
+      kind: a.kind,
+      difficulty: a.difficulty,
+      questionSet: a.questionSet,
+      jev: a.jev,
+    });
+  return {
+    lane: lane?.lane ?? null,
+    role: i.role,
+    ...a,
+    backend: parseRung(a.rung).backend,
+    agent: deps.profiles.agentFor(run.meta.repo, i.role, a.rung),
+  };
+}
+
+/** Evidence that the lane's own ownership is the problem: a design question, never a capability one. */
+const OWNERSHIP = /outside (the )?lane('s)? ownership|owned by/i;
+
+const CLIMB_DESIGN_FIX = "send it to the architect (ask/architect delta), not up the ladder";
+
+/**
+ * Spec 1.1 §9: a climb is for capability. Evidence that points at the plan (a contradiction, a file the
+ * lane does not own, a cross-lane interface) goes to the architect: ownership evidence on a `blocked`
+ * climb is refused outright; with Jev on, its `finding` answer `design` refuses any climb with evidence.
+ * A climb the environment caused (`env`) is never a design question.
+ */
+async function refuseDesign(
+  deps: Deps,
+  run: Run,
+  i: { lane: string; reason: ClimbReason; evidence?: string; env?: boolean },
+): Promise<void> {
+  if (!i.evidence || i.env) return;
+  if (i.reason === "blocked" && OWNERSHIP.test(i.evidence))
+    throw new CatherdError(
+      "E_CLIMB_DESIGN",
+      `climb ${i.lane}: the evidence is about lane ownership, which a higher rung cannot fix`,
+      { fix: CLIMB_DESIGN_FIX },
+    );
+  const use = deps.profiles.forRepo(run.meta.repo).jev.use;
+  if (use === "off") return;
+  const file = laneFile(run, i.lane);
+  if (!existsSync(file)) return;
+  const v = await deps.routing.finding(run.dir, readFileSync(file, "utf8"), i.evidence, use);
+  if (v.value === "design")
+    throw new CatherdError("E_CLIMB_DESIGN", `climb ${i.lane}: Jev calls the evidence a design finding`, {
+      fix: CLIMB_DESIGN_FIX,
+    });
+}
+
+/** Spec §4.5: one rung up the lane's ladder, on a fresh thread; the reason goes to routes.jsonl. */
+export async function climb(
+  deps: Deps,
+  i: { run: string; lane: string; reason: ClimbReason; evidence?: string; env?: boolean },
+): Promise<{
+  lane: string;
+  rung: string;
+  top: boolean;
+  backend: string;
+  agent: string | null;
+  hints?: string[];
+}> {
+  const run = findRun(i.run);
+  assertId("lane", i.lane);
+  const unrouted = () =>
+    new CatherdError("E_LANE_INVALID", `lane ${i.lane} was never routed`, {
+      fix: `route(run, "lanes/${i.lane}.md") first`,
+    });
+  // an unrouted lane is refused before Jev is asked about its evidence (no call, no jev.jsonl row)
+  if (!currentRoute(readRoutes(run), i.lane)) throw unrouted();
+  await refuseDesign(deps, run, i);
+  const { cur, next } = await withFileLock(runPaths(run.dir).routes, () => {
+    const cur = currentRoute(readRoutes(run), i.lane);
+    if (!cur) throw unrouted();
+    const next = nextRung(cur.ladder, cur.rung);
+    appendRoute(run, {
+      ...cur,
+      at: new Date(deps.now()).toISOString(),
+      source: "climb",
+      from: cur.rung,
+      rung: next ?? cur.rung,
+      reason: i.evidence ? `${i.reason}: ${i.evidence}` : i.reason,
+      env: i.env === true,
+    });
+    // spec §5.6: a climb past the top rung ends the lane open
+    if (!next) {
+      const o = laneOutcome(readRoutes(run), i.lane, false, new Date(deps.now()).toISOString());
+      if (o) appendOutcome(run, o);
+    }
+    return { cur, next };
+  });
+  const { hints } = await refreshState(run, {
+    next: next
+      ? `dispatch ${i.lane} at ${next} on a fresh thread`
+      : `${i.lane} failed on its top rung: ask finding, then the architect or the report`,
+  });
+  const rung = next ?? cur.rung;
+  return {
+    lane: i.lane,
+    rung,
+    top: next === null,
+    backend: parseRung(rung).backend,
+    agent: next ? deps.profiles.agentFor(run.meta.repo, cur.role, next) : null,
+    ...withHints(hints),
+  };
+}
+
+const cell = (s: string) => s.replace(/[|\n]/g, "/").replace(/\s+/g, " ").trim();
+
+export const LAND_SKIPS = ["docs-only", "no-code"] as const;
+export type LandSkip = (typeof LAND_SKIPS)[number];
+
+/**
+ * Spec 1.1 §6: a milestone lands only with a reviewer record and a verifier verdict since its lanes
+ * started, or with a `skip` the commit range bears out. Throws E_LAND_GATE naming what is missing.
+ */
+async function gate(run: Run, m: string, commit: string, skip: LandSkip | undefined): Promise<void> {
+  // spec 1.1 §8: a parked milestone waits on the owner, whatever else it has
+  const question = openQuestions(run).find((q) => q.milestone === m);
+  if (question)
+    throw new CatherdError(
+      "E_LAND_GATE",
+      `land ${m}: it is parked, waiting on the owner: ${question.question}`,
+      {
+        fix: `when the owner answers, call answer(run, "${m}", <their answer>), finish ${m}, then land it`,
+      },
+    );
+  if (skip) {
+    // the range a skip is judged on must be the milestone as it stands: an older commit would leave
+    // later source commits unreviewed
+    const [landed, head] = await Promise.all([fullCommit(run, commit), fullCommit(run, "HEAD")]);
+    if (landed !== head)
+      throw new CatherdError(
+        "E_LAND_GATE",
+        `land ${m}: skip "${skip}" refused: ${commit} is not HEAD (${head.slice(0, 7)}): commits after it would land unreviewed`,
+        {
+          fix: `land ${m} with HEAD (${head.slice(0, 7)}) once it holds the milestone; if source changed, run reviewer-${m} and the verifier and land without skip`,
+        },
+      );
+    const files = await milestoneFiles(run, commit);
+    // an empty range lands nothing: the milestone's work is most likely not committed yet
+    if (files.length === 0) {
+      const last = landedMilestones(run).at(-1);
+      throw new CatherdError(
+        "E_LAND_GATE",
+        `land ${m}: skip "${skip}" refused: ${last ? `the commit range changed nothing since ${last} landed` : `${commit} changed nothing`}`,
+        { fix: `commit the milestone first, then land ${m} with that commit` },
+      );
+    }
+    const against =
+      skip === "docs-only" ? files.filter((f) => !isDocPath(f)) : files.filter((f) => isSourcePath(f));
+    if (against.length === 0) return;
+    const shown = `${against.slice(0, 5).join(", ")}${against.length > 5 ? `, and ${against.length - 5} more` : ""}`;
+    throw new CatherdError(
+      "E_LAND_GATE",
+      `land ${m}: skip "${skip}" refused: ${skip === "docs-only" ? "files outside the docs changed" : "source files changed"}: ${shown}`,
+      { fix: `run the reviewer (reviewer-${m}) and the verifier on ${m}, then land it without skip` },
+    );
+  }
+  const start = milestoneStart(run, m);
+  // the latest verifier attempt, passed or not: a FAIL after a PASS undoes it
+  const verdict = milestoneVerifier(run, m, start);
+  const missing = [
+    ...(reviewerPassed(run, m, start)
+      ? []
+      : [
+          `a reviewer record (a dispatch named reviewer-${m}, or record_agent_run with role reviewer and that name, status ok)`,
+        ]),
+    ...(verdict?.passed
+      ? []
+      : [
+          `a verifier verdict (record_agent_run with role verifier and a name holding ${m}, status ok; a headless verifier's reply opening VERDICT: PASS)${verdict ? `: the latest, ${verdict.name}${verdict.headless ? " (headless)" : ""}, is ${verdict.verdict}` : ""}`,
+        ]),
+  ];
+  if (missing.length)
+    throw new CatherdError(
+      "E_LAND_GATE",
+      `land ${m}: missing ${missing.join(" and ")}, since its lanes started`,
+      {
+        fix: `run reviewer-${m} (a dispatch, or a Claude subagent recorded with record_agent_run(name: "reviewer-${m}")) and the verifier on ${m}, recording it with record_agent_run(name: "verifier-${m}") (a FAIL with status "failed"), then land again; a docs-only milestone passes skip: "docs-only"`,
+      },
+    );
+}
+
+/**
+ * Spec §4.7: the full five-column ledger row, with the minutes since the previous landing (or the
+ * run's start), and `learned` appended to the repo's knowledge.md.
+ */
+export async function land(
+  deps: Deps,
+  i: {
+    run: string;
+    milestone: string;
+    what: string;
+    commit: string;
+    evidence: string;
+    next: string;
+    learned?: string;
+    skip?: LandSkip;
+  },
+): Promise<{ ledger: string; minutes: number; digest: string; hints?: string[] }> {
+  const run = findRun(i.run);
+  // the digest is named after the milestone: an id, checked before anything is written
+  assertId("milestone", i.milestone);
+  // commitExists throws E_IO_UNEXPECTED on a timeout, which reaches the caller as is
+  if (!/^[0-9a-f]{7,40}$/.test(i.commit) || !(await commitExists(run.meta.repo, i.commit)))
+    throw new CatherdError("E_RUN_COMMIT", `no commit ${i.commit} in ${run.meta.repo}`, {
+      fix: "commit the milestone first, then pass its hash",
+    });
+  await gate(run, i.milestone, i.commit, i.skip);
+  const now = new Date(deps.now());
+  let row = "";
+  let minutes = 0;
+  const landRow = (notes: Notes): NotesPatch => {
+    minutes = Math.max(
+      0,
+      Math.round((now.getTime() - Date.parse(notes.lastLandedAt ?? run.meta.createdAt)) / 60_000),
+    );
+    row = [i.milestone, i.what, i.commit, String(minutes), i.evidence].map(cell).join(" | ");
+    appendLedger(run, row);
+    return { lastCheck: cell(i.evidence), next: i.next, lastLandedAt: now.toISOString() };
+  };
+  // on a failed refresh the notes still reach state.json, so the next landing counts its minutes from this one
+  const { hints } = await refreshState(run, landRow);
+  // spec §5.6: every routed lane of the milestone lands with it
+  // under the routes lock, so a racing climb cannot slip between the read and the rows
+  let routed: string[] = [];
+  let landed = 0;
+  await withFileLock(runPaths(run.dir).routes, () => {
+    const routes = readRoutes(run);
+    routed = [...new Set(routes.map((r) => r.lane))];
+    for (const lane of routed)
+      if (lane.startsWith(`${i.milestone}.`)) {
+        landed++;
+        const o = laneOutcome(routes, lane, true, now.toISOString());
+        if (o) appendOutcome(run, o);
+      }
+  });
+  // a milestone name no routed lane starts with is most likely a typo: say so rather than record nothing
+  if (routed.length > 0 && landed === 0)
+    hints.push(
+      `land: no routed lane is in milestone "${i.milestone}" (routed: ${routed.slice(0, 5).join(", ")}${routed.length > 5 ? ", …" : ""}); check its name: no lane outcome was recorded`,
+    );
+  if (i.learned) {
+    appendPrivate(
+      knowledgeFile(run.meta.repo),
+      `- ${now.toISOString().slice(0, 10)} ${run.meta.title} ${i.milestone}: ${cell(i.learned)}\n`,
+    );
+  }
+  // spec 1.1 §10: the milestone's digest, which the milestone push links
+  const digest = writeDigest(run, {
+    milestone: i.milestone,
+    what: i.what,
+    commit: i.commit,
+    evidence: i.evidence,
+    minutes,
+    at: now.toISOString(),
+  });
+  return { ledger: row, minutes, digest, ...withHints(hints) };
+}
+
+/** Jev's `finding` or `same-defect` answer, through the routing port. */
+export async function ask(
+  deps: Deps,
+  i: { run: string; question: "finding" | "same-defect"; state: Record<string, string> },
+): Promise<Verdict<string>> {
+  const run = findRun(i.run);
+  const need = (k: string): string => {
+    const v = i.state[k];
+    if (!v)
+      throw new CatherdError("E_INPUT_INVALID", `ask ${i.question} needs state.${k}`, {
+        fix: i.question === "finding" ? "pass state { lane_file, finding }" : "pass state { before, after }",
+      });
+    return v;
+  };
+  // spec §5.5: a profile with Jev off never asks it, for routing or for these verdicts
+  const use = deps.profiles.forRepo(run.meta.repo).jev.use;
+  if (i.question === "finding") {
+    const { text } = readLaneFile(run, need("lane_file"));
+    return deps.routing.finding(run.dir, text, need("finding"), use);
+  }
+  return deps.routing.sameDefect(run.dir, need("before"), need("after"), use);
+}