omp-conductor 0.18.0 → 0.18.2

package/src/admission.ts

@@ -18,9 +18,13 @@ import { join } from "node:path";
 import { log, errText, safeEscalate } from "./log.ts";
 import type {
   Caps,
+  EffectiveModel,
   Escalation,
+  FileLane,
   IssueComment,
   IssueSnapshot,
+  LaneDeclaration,
+  ModelDeclaration,
   OpenCloser,
   ProjectConfig,
   RunRecord,
@@ -94,11 +98,16 @@ export function hasFailedAttemptBudget(failures: number, maxAttempts: number): b
  *  (#608): the exact snapshot the overlap gate enforced. Dispatch renders this
  *  value into the worker brief, so a changed or failed second comment read can
  *  neither hide nor reword the lane admission held — the gate and the
- *  worker-visible brief are one value, not two reads of the same thread. */
+ *  worker-visible brief are one value, not two reads of the same thread.
+ *  `model` is the effective `Model:` declaration resolved from the same read
+ *  (#535): not a gate, but the same one-value contract — dispatch launches on
+ *  this selector and the brief echoes it, so a second read can neither hide
+ *  the model admission held nor drift from it. */
 export interface Admission {
   r: Routed;
   attempt: number;
   lane?: FileLane;
+  model?: EffectiveModel;
 }
 
 export interface AdmissionHold {
@@ -192,20 +201,42 @@ function planUsageEscalation(project: string, plan: PlanUsageStatus): Escalation
  * files an issue declares it will touch (#555).
  *
  * The orchestrator already writes exactly this list into every promotion brief
- * in prose; this parses that same sentence out of the issue body — or out of a
- * pre-dispatch comment, which is the same sentence on a supported brief
+ * in prose; this parses that same declaration out of the issue body — or out of
+ * a pre-dispatch comment, which is the same declaration on a supported brief
  * surface since #517 — so the interlock is load-bearing rather than advisory.
- * A line beginning with "file lane" (case-insensitive, optional
- * bold/heading markers) is accepted, and paths are read as backtick-delimited
- * spans (the brief form) with a bare comma/space-separated fallback that keeps
- * tokens that look like relative paths. A line whose tokens are not pathlike
- * (like `File lane: none`) is not a declaration. Anything else — including an
+ * Two spellings are accepted, and both work on every surface:
+ *
+ * - The inline line: a line beginning with "file lane" (case-insensitive,
+ *   optional bold/heading markers) whose rest carries the paths as
+ *   backtick-delimited spans (the brief form), with a bare
+ *   comma/space-separated fallback that keeps tokens that look like relative
+ *   paths.
+ * - The write-lane section (#825): a markdown heading "Exact write lane" (or
+ *   "Write lane" / "write-lane") whose immediately following bullet items
+ *   carry the paths — the package-floor decomposition format, where a groomed
+ *   child names the files it writes as one backticked path per bullet. Only
+ *   the contiguous bullet run under that heading is read: a following
+ *   paragraph (like a "Read only:" caveat) or a later section ends it, so
+ *   read-only entry points, proof commands and acceptance bullets elsewhere in
+ *   the issue are never captured.
+ *
+ * Inline wins when both are present — the machine-shaped sentence has held
+ * since #555, and the mediated label echo shows exactly which declaration
+ * admission enforces. A line or section whose tokens are not pathlike (like
+ * `File lane: none`) is not a declaration. Anything else — including an
  * absent declaration, which is the default — is an empty lane: the issue is
  * admitted exactly as today (`fail open`), and the gate never refuses work for
- * wanting a lane. This is the one grammar for all surfaces; there is no second
- * comment-only spelling.
+ * wanting a lane. A clearly delimited write-lane section that parsed nothing
+ * is NOT an absent declaration: the promotion verb refuses it with an
+ * actionable syntax error ({@link writeLaneSectionHeading}) rather than
+ * echoing a fail-open the section's own heading contradicts.
  */
 export function laneDeclaration(text: string): LaneDeclaration | undefined {
+  return inlineLaneDeclaration(text) ?? sectionLaneDeclaration(text);
+}
+
+/** The inline `File lane:`/`File-lane=` sentence grammar (see {@link laneDeclaration}). */
+function inlineLaneDeclaration(text: string): LaneDeclaration | undefined {
   const match = text.match(
     /^\s*(?:[#>*-]\s*)*file[- ]lane\s*[:=]\s*([^\n]*)$/im,
   );
@@ -222,34 +253,58 @@ export function laneDeclaration(text: string): LaneDeclaration | undefined {
   return { files, source: match[0].trim() };
 }
 
-/** One parsed `File lane:` declaration: the paths and the verbatim source
- *  line, so a renderer can reproduce the declaration itself rather than a
- *  summary of it. Exported for the brief's guarantee that the gate's effective
- *  lane is always visible to the worker (#608). */
-export interface LaneDeclaration {
-  files: string[];
-  /** The declaration line verbatim, as written on the surface it came from. */
-  source: string;
-}
-
 /**
- * The effective file lane as both admission and the worker brief must read it
- * (#608): the latest `File lane:` declaration among the issue body and every
- * comment, in the tracker's oldest-first order. This is the "later correction
- * visibly supersedes" contract applied across both surfaces at once, and it is
- * the single source of truth the gate enforces and the brief renders — so a
- * declaration can never control admission while staying invisible to the
- * worker. `at` records which surface won (`"body"`, or the 0-based comment
- * index), letting the brief reproduce the declaration verbatim when the
- * winning comment sits beyond its rendered discussion budget.
+ * A markdown heading that opens a clearly delimited write-lane section
+ * (#825): `## Exact write lane`, `## Write lane`, or a hyphenated spelling,
+ * optional trailing colon. Returns the heading line verbatim, or undefined.
+ * The promotion verb uses this to refuse a section that parsed to nothing —
+ * the echo must never claim fail-open for a heading that plainly tried to
+ * declare one.
  */
-export interface FileLane extends LaneDeclaration {
-  at: "body" | number;
+export function writeLaneSectionHeading(text: string): string | undefined {
+  const match = text.match(
+    /^[ \t]*#{1,6}[ \t]+(?:exact[ \t]+)?write[-\s]lane[ \t]*[:.]?[ \t]*$/im,
+  );
+  return match === null ? undefined : match[0].trim();
+}
+
+/** The write-lane section grammar (see {@link laneDeclaration}): the heading
+ *  plus the contiguous bullet run beneath it. A non-bullet line ends the run,
+ *  so a caveat paragraph or the next section bounds the declaration. */
+function sectionLaneDeclaration(text: string): LaneDeclaration | undefined {
+  const lines = text.split("\n");
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (writeLaneSectionHeading(lines[i]!) !== undefined) {
+      start = i;
+      break;
+    }
+  }
+  if (start < 0) return undefined;
+  const files: string[] = [];
+  const bullets: string[] = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (line.trim() === "") continue;
+    // A markdown bullet marker (`- `, `* `, `+ `, `1. `), with an optional
+    // task checkbox. Anything else ends the section's bullet run.
+    const marker = line.match(/^[ \t]*(?:[-*+]|\d+[.)])[ \t]+(?:\[[ xX]\][ \t]+)?/);
+    if (marker === null) break;
+    const rest = line.slice(marker[0].length);
+    const backticked = [...rest.matchAll(/`([^`]+)`/g)]
+      .map((m) => m[1]!.trim())
+      .filter(isPathLike);
+    files.push(...(backticked.length > 0 ? backticked : rest.split(/[,\s]+/).map((s) => s.trim()).filter(isPathLike)));
+    bullets.push(line.trim());
+  }
+  if (files.length === 0) return undefined;
+  return { files: [...new Set(files)], source: [lines[start]!.trim(), ...bullets].join("\n") };
 }
 
 /** Who holds one file's lane this admission pass, and which read proved it.
- *  `"declared"` is the same-pass half: an admitted candidate's own lane
- *  occupies for the rest of the pass without any probe read. */
+ *  `"declared"` covers both occupancy halves: an admitted candidate's own
+ *  lane for the rest of its pass, and — since #744 — a live run's persisted
+ *  declaration on every later pass, without any probe read. */
 export type LaneHolder = { issue: number; source: LaneSource | "declared" };
 
 /** Resolves the effective lane across the body and the whole comment thread. */
@@ -270,6 +325,41 @@ export function declaredLane(body: string): string[] {
   return laneDeclaration(body)?.files ?? [];
 }
 
+/**
+ * The model half of a promotion brief (#535): the selector an issue declares
+ * it will dispatch on, read from the body or a pre-dispatch comment — the
+ * same two surfaces `File lane:` reads. Conductor names a selector and omp
+ * resolves what it means, so the declaration is one token in omp's own model
+ * syntax — a role alias (`@slow`) or a concrete `provider/model`, either
+ * optionally `:thinking`-suffixed — passed through verbatim as the session's
+ * `modelPattern`. A line whose rest is not exactly one selector (blank,
+ * `none`, multi-word prose) is not a declaration: dispatch fails open to the
+ * project's `workerModel`, exactly as a lane-less issue is admitted today.
+ * This is the one grammar for all surfaces; there is no second comment-only
+ * spelling.
+ */
+export function modelDeclaration(text: string): ModelDeclaration | undefined {
+  const match = text.match(
+    /^\s*(?:[#>*-]\s*)*model\s*[:=]\s*([^\n]*)$/im,
+  );
+  if (match === null) return undefined;
+  const rest = (match[1] ?? "").trim().replace(/^[*`\s]+|[*`\s]+$/g, "").trim();
+  if (rest === "" || /^none$/i.test(rest) || /\s/.test(rest)) return undefined;
+  return { model: rest, source: match[0].trim() };
+}
+
+/** Resolves the effective model across the body and the whole comment thread. */
+export function effectiveModel(body: string, comments: IssueComment[]): EffectiveModel | undefined {
+  let current: EffectiveModel | undefined;
+  const bodyDecl = modelDeclaration(body);
+  if (bodyDecl !== undefined) current = { ...bodyDecl, at: "body" };
+  for (let i = 0; i < comments.length; i++) {
+    const decl = modelDeclaration(comments[i]!.body);
+    if (decl !== undefined) current = { ...decl, at: i };
+  }
+  return current;
+}
+
 /**
  * The file lane as one line, for surfaces where a human asserts the claim
  * (#724): the parsed file list exactly as admission will enforce it, or the
@@ -348,43 +438,61 @@ export async function admitCandidates(
   };
 
   // The file-lane interlock (#555): repo -> file -> the issue holding that file.
-  // Seeded from the *actual* worktrees/branches of active runs — never from
-  // their issue bodies, which is precisely how #288 collided — and extended as
-  // this pass admits candidates with declared lanes, so two overlapping
-  // candidates cannot both clear the gate in one tick. Keyed by repo because a
-  // path only collides within its own checkout: a `daemon.ts` on the api repo
-  // and one on the web repo are different files. Built lazily and once, only
-  // when the first candidate that declares a lane reaches the gate, so a queue
-  // of laneless issues pays nothing for it.
+  // Seeded from what a live run actually *occupies*, never from its issue body:
+  // the probed worktrees/branches of active runs (#288) unioned — since #744 —
+  // with the lane declaration admission persisted on the row at dispatch, which
+  // is the exact enforced snapshot, not a re-parse. The declared half is what
+  // survives across passes: a run admitted with a lane it has not yet written
+  // still occupies until it reaches a terminal state and leaves the active set,
+  // and the declared lanes are extended as this pass admits candidates, so two
+  // overlapping candidates cannot both clear the gate in one tick. Keyed by
+  // repo because a path only collides within its own checkout: a `daemon.ts` on
+  // the api repo and one on the web repo are different files. Built lazily and
+  // once, only when the first candidate that declares a lane reaches the gate,
+  // so a queue of laneless issues pays nothing for it.
   let laneOccupancy: Map<string, Map<string, LaneHolder>> | undefined;
   const ensureLaneOccupancy = async (): Promise<Map<string, Map<string, LaneHolder>>> => {
     if (laneOccupancy !== undefined) return laneOccupancy;
     const occupied = new Map<string, Map<string, LaneHolder>>();
-    for (const run of activeRuns) {
-      if (d.probeWorktreeLane === undefined) break;
-      const base = project.routing.repos[run.repo]?.defaultBranch ?? "main";
-      let files: LaneFile[];
-      try {
-        files = await d.probeWorktreeLane({
-          worktree: run.worktree,
-          baseRef: `refs/remotes/origin/${base}`,
-          ...(run.branch === "" ? {} : { branchRef: `refs/heads/${run.branch}` }),
-          mirror: join(project.mirrorRoot, `${run.repo}.git`),
-        });
-      } catch {
-        // Fail open, like an unreadable lane: the gate never refuses a
-        // well-formed issue because one probe could not be answered.
-        files = [];
+    // Shared per-file first-read-wins: a file a run both declares and has
+    // actually touched is tagged by the concrete probe read, and across runs
+    // whichever live run comes first in the active set is the holder named —
+    // both are legitimate for the gate, which holds on any overlap.
+    const occupy = (run: RunRecord, file: string, source: LaneSource | "declared"): void => {
+      let perRepo = occupied.get(run.repo);
+      if (perRepo === undefined) {
+        perRepo = new Map();
+        occupied.set(run.repo, perRepo);
       }
-      for (const { file, source } of files) {
-        let perRepo = occupied.get(run.repo);
-        if (perRepo === undefined) {
-          perRepo = new Map();
-          occupied.set(run.repo, perRepo);
+      if (!perRepo.has(file)) perRepo.set(file, { issue: run.issue, source });
+    };
+    for (const run of activeRuns) {
+      // The probed actual half first, so the concrete read outnames the
+      // declaration for a file the run has already written.
+      if (d.probeWorktreeLane !== undefined) {
+        const base = project.routing.repos[run.repo]?.defaultBranch ?? "main";
+        let files: LaneFile[];
+        try {
+          files = await d.probeWorktreeLane({
+            worktree: run.worktree,
+            baseRef: `refs/remotes/origin/${base}`,
+            ...(run.branch === "" ? {} : { branchRef: `refs/heads/${run.branch}` }),
+            mirror: join(project.mirrorRoot, `${run.repo}.git`),
+          });
+        } catch {
+          // Fail open, like an unreadable lane: the gate never refuses a
+          // well-formed issue because one probe could not be answered.
+          files = [];
         }
-        // First read wins: a file the run both commits and edits in its
-        // worktree is tagged by its live uncommitted half.
-        if (!perRepo.has(file)) perRepo.set(file, { issue: run.issue, source });
+        for (const { file, source } of files) occupy(run, file, source);
+      }
+      // The declared durable half (#744): the lane admission persisted at
+      // dispatch. Occupies even before the run has written anything, on every
+      // pass — the declaration lives on the row, not in a per-pass memo.
+      // Released by the active-set filter exactly like probed occupancy: a
+      // terminal run leaves `activeRuns` and its files stop occupying here.
+      if (run.lane !== undefined && run.lane.files.length > 0) {
+        for (const file of run.lane.files) occupy(run, file, "declared");
       }
     }
     laneOccupancy = occupied;
@@ -408,31 +516,45 @@ export async function admitCandidates(
   // the worker therefore agree on one lane, which is the #608 defect's shape.
   //
   // Comments are read at most once per issue per pass — the lane feeds both
-  // the gate and the same-pass sibling occupancy below, so the cache is what
-  // stops one candidate costing two comment reads. Unreadable comments fail
-  // open to the body declaration (a body lane stays load-bearing), and with no
-  // readable declaration at all the #555 fail-open admission is unchanged.
+  // the gate and the same-pass sibling occupancy below, and the model rides
+  // the same read for its one-value contract with dispatch (#535), so the
+  // cache is what stops one candidate costing two comment reads. Unreadable
+  // comments fail open to the body declarations (a body lane stays
+  // load-bearing, and a body model stays the one dispatch follows), and with
+  // no readable declaration at all the #555 fail-open admission is unchanged.
   //
   // The resolved `FileLane` — not just its paths — is what an admitted
   // candidate carries into dispatch (#608): the gate and the brief must agree
   // on the *same declaration* (paths, verbatim source line, and which surface
   // it came from), so dispatch renders this cached value rather than reading
-  // the thread a second time and hoping it did not change.
+  // the thread a second time and hoping it did not change. The resolved
+  // `EffectiveModel` is carried the same way and for the same reason: dispatch
+  // launches on exactly this selector and the brief echoes it.
   const laneCache = new Map<number, FileLane | undefined>();
-  const laneFor = async (r: Routed): Promise<FileLane | undefined> => {
+  const modelCache = new Map<number, EffectiveModel | undefined>();
+  const declarationsFor = async (r: Routed): Promise<void> => {
     const issue = r.issue.number;
-    if (laneCache.has(issue)) return laneCache.get(issue);
+    if (laneCache.has(issue)) return;
     let lane: FileLane | undefined;
+    let model: EffectiveModel | undefined;
     try {
-      lane = effectiveLane(r.issue.body, await tracker.listComments(issue));
+      const comments = await tracker.listComments(issue);
+      lane = effectiveLane(r.issue.body, comments);
+      model = effectiveModel(r.issue.body, comments);
     } catch (err) {
       const bodyDecl = laneDeclaration(r.issue.body);
       lane = bodyDecl === undefined ? undefined : { ...bodyDecl, at: "body" };
-      log(`#${issue} comments unreadable at admission; the body's file lane stands: ${errText(err)}`);
+      const bodyModel = modelDeclaration(r.issue.body);
+      model = bodyModel === undefined ? undefined : { ...bodyModel, at: "body" };
+      log(`#${issue} comments unreadable at admission; the body's declarations stand: ${errText(err)}`);
     }
     laneCache.set(issue, lane);
-    return lane;
+    modelCache.set(issue, model);
   };
+  const laneFor = (r: Routed): Promise<FileLane | undefined> =>
+    declarationsFor(r).then(() => laneCache.get(r.issue.number));
+  const modelFor = (r: Routed): Promise<EffectiveModel | undefined> =>
+    declarationsFor(r).then(() => modelCache.get(r.issue.number));
 
   // The plan allowance is a fleet-wide question, so it is asked once per pass
   // and answers for every candidate — unlike every gate below it, which is
@@ -450,6 +572,9 @@ export async function admitCandidates(
     log(`plan usage gate holding ${String(routed.length)} candidate(s): ${plan.detail}`);
     const escalation = planUsageEscalation(project.name, plan);
     if (escalation !== undefined) await safeEscalate(d, escalation);
+    // Every pass exit reconciles the durable blocked inventory against this
+    // pass's holds, so a hold that stopped applying clears itself (#735).
+    store.reconcileGrooming(project.name, holds);
     return { admitted: [], holds };
   }
 
@@ -1035,7 +1160,7 @@ export async function admitCandidates(
       if (blocked) continue;
     }
 
-    admitted.push({ r, attempt: priorRuns + 1, lane });
+    admitted.push({ r, attempt: priorRuns + 1, lane, model: await modelFor(r) });
     liveByRepo.set(r.repo.name, (liveByRepo.get(r.repo.name) ?? 0) + 1);
     // Same-pass sibling occupancy for the file-lane gate: once admitted, a
     // candidate's declared lane occupies for the rest of the pass, so a later
@@ -1064,5 +1189,9 @@ export async function admitCandidates(
     }
   }
 
+  // Every pass exit reconciles the durable blocked inventory against this
+  // pass's holds, so a lane/dependency hold that stopped applying clears
+  // itself on the very next pass (#735).
+  store.reconcileGrooming(project.name, holds);
   return { admitted, holds };
 }