agent-coord-mcp 0.26.20 → 0.26.21

package/src/gated-head.ts

@@ -0,0 +1,134 @@
+/*
+ * ⛔⛆ THE THING MERGED MUST BE THE THING GATED — AND NOTHING COMPARED THEM.
+ *
+ * `⟨q-6a4f0c38⟩`, from a real breach on kit#268. The sequence, which no single
+ * seat could see alone:
+ *
+ *   10:23:14Z  QA posts PASS bound to 6051193
+ *   10:23:22Z  the merge runs           <- 8 seconds later
+ *              but the branch head was 1d6deab by then: an author force-pushed
+ *   10:28:06Z  QA re-issues PASS bound to 1d6deab, AFTER the fact
+ *
+ * Three controls had to fail together: the force-push created the opportunity,
+ * the merge did not re-read the head, and the recording step did not compare.
+ * This module is the predicate for the two that are mechanisable.
+ *
+ * ⭐ WHY THE CHECK MUST BE TEMPORAL, and this is the trap that makes the naive
+ * version certify the very breach it was built for: by the time anyone looks,
+ * a PASS bound to `1d6deab` EXISTS. "Is there a PASS for the merged head?" is
+ * TRUE for #268 today. Only "was there one AT OR BEFORE the merge" is false.
+ * A re-issued verdict is an honest record that the CONTENT was verified; it is
+ * not evidence that the MERGE was gated, and conflating them erases the event.
+ *
+ * ⭐ WHY THE SHA COMPARISON IS PREFIX-TOLERANT RATHER THAN EQUALITY. Measured
+ * across all 45 verdict records on this fleet's room log:
+ *
+ *     headRefOid length:  7 chars -> 14 records,  40 chars -> 31 records
+ *
+ * Verdicts are written by hand and abbreviate. An exact compare against `gh`'s
+ * 40-char head would report "never gated" on ~31% of verdicts that DID gate —
+ * false positives on correct merges, which is the failure that gets a check
+ * switched off. MIN_SHA guards the other direction: a 4-character "sha" is not
+ * an identifier, it is a collision, so it is REFUSED rather than matched.
+ *
+ * ⛔ AND "COULD NOT CHECK" IS NEVER "CHECKED AND CLEAN" — the rule this repo
+ * already applies in `versionDrift`. No verdict found, an unreadable log and an
+ * unreachable `gh` are each a REFUSAL with a reason, never a pass.
+ */
+
+/** Below this, an abbreviation is a collision rather than an identifier. */
+export const MIN_SHA = 7;
+
+/**
+ * Do two object names refer to the same commit, allowing either to be
+ * abbreviated? Case-insensitive; hex only; both must reach MIN_SHA.
+ */
+export function shaAgrees(a: string | undefined, b: string | undefined): boolean {
+  const x = (a ?? "").trim().toLowerCase();
+  const y = (b ?? "").trim().toLowerCase();
+  if (!/^[0-9a-f]+$/.test(x) || !/^[0-9a-f]+$/.test(y)) return false;
+  if (x.length < MIN_SHA || y.length < MIN_SHA) return false;
+  return x.length <= y.length ? y.startsWith(x) : x.startsWith(y);
+}
+
+export type PassVerdict = { head: string; ts: number; from: string; result: string };
+
+/** The PR number a verdict record is about, from its `cites`. */
+function citedPr(cites: unknown): string | null {
+  if (!Array.isArray(cites)) return null;
+  for (const c of cites) {
+    const ref = String((c as { ref?: unknown })?.ref ?? "");
+    const m = ref.match(/#(\d+)/);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+/**
+ * Every verdict record in a room log that is about PR `pr`.
+ *
+ * Tolerant of unparseable lines by SKIPPING them and reporting how many, rather
+ * than throwing: a log this cannot fully read still answers the question for the
+ * lines it can, and the caller is told the denominator it actually saw.
+ */
+export function verdictsFor(logText: string, pr: string): { verdicts: PassVerdict[]; lines: number; unparsed: number } {
+  const lines = logText.split("\n").filter((l) => l.trim());
+  let unparsed = 0;
+  const verdicts: PassVerdict[] = [];
+  for (const l of lines) {
+    let o: Record<string, unknown>;
+    try {
+      o = JSON.parse(l) as Record<string, unknown>;
+    } catch {
+      unparsed++;
+      continue;
+    }
+    const r = o.record as { type?: string; payload?: Record<string, unknown>; cites?: unknown } | undefined;
+    if (!r || r.type !== "verdict") continue;
+    if (citedPr(r.cites) !== pr) continue;
+    verdicts.push({
+      head: String(r.payload?.headRefOid ?? ""),
+      ts: Number(o.ts ?? 0),
+      from: String(o.from ?? ""),
+      result: String(r.payload?.result ?? ""),
+    });
+  }
+  return { verdicts, lines: lines.length, unparsed };
+}
+
+export type GateAnswer =
+  | { gated: true; by: PassVerdict }
+  | { gated: false; reason: string; crossed?: { gatedSha: string; at: number }[] };
+
+/**
+ * Was `head` gated by a PASS that existed at or before `at`?
+ *
+ * `at` is the decisive argument. Pass the merge time to ask "was this merge
+ * gated"; pass `Date.now()` to ask "is this head gated right now", which is the
+ * pre-merge question. Same predicate, two positions.
+ */
+export function gatedAt(verdicts: PassVerdict[], head: string, at: number): GateAnswer {
+  const passes = verdicts.filter((v) => v.result === "pass");
+  if (passes.length === 0) {
+    return { gated: false, reason: `no PASS verdict was ever recorded for this PR — not checked, which is not the same as checked and passing` };
+  }
+  const inTime = passes.filter((v) => v.ts <= at);
+  if (inTime.length === 0) {
+    return {
+      gated: false,
+      reason:
+        `every PASS for this PR was recorded AFTER the moment being judged — a verdict posted later says the content ` +
+        `was verified, never that this merge was gated`,
+      crossed: passes.map((v) => ({ gatedSha: v.head, at: v.ts })),
+    };
+  }
+  const match = inTime.find((v) => shaAgrees(v.head, head));
+  if (match) return { gated: true, by: match };
+  return {
+    gated: false,
+    reason:
+      `the head being judged (${head.slice(0, 7)}) matches no PASS recorded at or before that moment — ` +
+      `the thing merged is not the thing gated`,
+    crossed: inTime.map((v) => ({ gatedSha: v.head, at: v.ts })),
+  };
+}

package/src/server.ts

@@ -113,6 +113,7 @@ import {
   exportWorkTool,
   isPidAlive,
 } from "./tools/index.js";
+import { queueWriteSchema, queueWriteTool } from "./tools/queue-write.js";
 
 function jsonResult(data: unknown) {
   return {
@@ -690,6 +691,13 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     gate(null, landTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
+  addTool(
+    "queue_write",
+    "FILE, AMEND, REPRIORITISE or RETAG a queue item by passing FIELDS \u2014 never markdown. The verb owns the grammar, mints and stamps the id, and writes the file; direct editing of docs/QUEUE.md is the exception, not the route. `op:'file'` needs text + priority and mints the id; `op:'amend'` needs id + text; `op:'reprioritise'` needs id + priority; `op:'retag'` needs id + tags and REFUSES text, because it exists so a routing tag can be set WITHOUT rewriting the item's prose \u2014 a verb that makes you restate the row to set one field is a verb nobody uses at the transition. `tags` carries the leading-tag family as fields (`awaits`, `sweep`); null clears a key and an omitted key is left alone, so setting `awaits` never drops a `sweep` the row carries. A tag inside `text` is still REFUSED: the position after the id is machine-readable and `next_unblocked` routes on it, so a field satisfiable by prose would be the defect rather than the fix. `undelivered` is not settable \u2014 it is derived from the publish record. Refuses multi-line text, because queue.v1 is one line per item and every parser drops a continuation silently. Refuses when the file moved under it rather than clobbering another writer, and returns the id, priority, text, the tags the row PARSES as, and what it wrote \u2014 no markdown in either direction.",
+    queueWriteSchema,
+    gate(null, queueWriteTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
   addTool(
     "merge",
     "Merge a PR ONLY as the consequence of its check verdict: reads the status rollup and merges in the same call, so there is no ordering in which the check runs and the merge ignores it. Refuses on any failing check, on any check not yet terminal, on a CONFLICTING base, and on ZERO checks \u2014 no checks is not passing checks, an empty rollup has zero failures and evidences nothing. Every return carries the POPULATION it judged. Reports by default; pass write:true to merge.",

package/src/tools/queue-write.ts

@@ -0,0 +1,485 @@
+/*
+ * `queue_write` — FILE, AMEND and REPRIORITISE a queue item through a verb.
+ *
+ * ⭐ DAVID SET THE LEVEL OF THIS API, NOT JUST ITS EXISTENCE (2026-09-09):
+ *   "where possible we should hide the plumbing from the agents. with a tool he
+ *    can just say task x is ready and then the tool moves it to done."
+ *   "as long as we offer enough tooling to support future reads and writes
+ *    through tools we should as much as possible discourage direct file editing.
+ *    we also should avoid token costs an agent patching lines would cost tokens."
+ *
+ * ⛔ SO THE SURFACE IS INTENT PLUS EVIDENCE, NEVER FIELDS PLUS FORMAT. The caller
+ * says WHAT the item is and HOW URGENT; this module owns the grammar, the id, the
+ * glyphs and the file. **No caller-supplied string reaches a document verbatim**
+ * — `text` is carried inside a modelled `QueueItem` and rendered by the seam's
+ * `renderQueueLine`, which is the same function the parser round-trips against.
+ * A verb that accepted a pre-formatted row would be hand-editing with an API on
+ * top, which is the defect this row names.
+ *
+ * WHY THE AGENT MUST NOT KNOW THE GRAMMAR — an inventory, not a preference. Every
+ * one of these cost this fleet something in one week, and not one is a rule an
+ * agent should ever have had to know:
+ *   · the closing citation must sit on the item's OWN FIRST LINE (⟨q-6d21ff84⟩,
+ *     paid for twice, and a continuation line does not satisfy it)
+ *   · every item must carry a RECORDED id and the writer must stamp it
+ *     (⟨q-c50e9b83⟩, which reddened `main` twice in six minutes)
+ *   · `queue.v1` is ONE LINE PER ITEM — a wrapped continuation is dropped by
+ *     every parser (⟨q-8c1f04b7⟩: 83% of one item's content lost)
+ *   · conflict markers committed into QUEUE.md with every gate green
+ * Each disappears behind a verb that renders the line itself.
+ *
+ * CONCURRENCY is not handled here and that is deliberate: every write goes
+ * through `writeDoc`, which re-reads and REFUSES a moved base (⟨q-0c5e73a1⟩).
+ * This module would be unsafe without it, which is why that landed first.
+ */
+import { z } from "zod";
+import path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import {
+  parseWorkDoc,
+  queueItemsOf,
+  withRecordedId,
+  renderQueueLine,
+  leadingTagsOf,
+  type LeadingTag,
+  type QueueItem,
+  type WorkDoc,
+} from "@davidbalzan/groundwork-seam";
+import { writeDoc, StaleWriteError } from "./records.js";
+
+const QUEUE_DOC = "docs/QUEUE.md";
+const PRIORITIES = ["P1", "P2", "P3"] as const;
+
+/**
+ * ⛔ THE GUARD MUST ASK ABOUT THE ROW AS IT WILL BE *READ*, NOT AS IT WAS BUILT.
+ *
+ * QA FAIL on #263 @ 05bf3ee: `"   **[AWAITS:david]** x"` — leading whitespace, a
+ * TAB too — passed the gate and landed LIVE. Measured, both halves:
+ *
+ *   pre-id item   text `"   **[AWAITS..."`   leadingTagsOf -> []
+ *   as written    text `"**[AWAITS..."`      leadingTagsOf -> [{awaits:david}]
+ *
+ * `LEADING_TAG` is anchored `^\*\*\[`, so the spaces hid the tag from it. Then
+ * `renderQueueLine` stamps the id, and the parser's id-strip consumes exactly
+ * that whitespace — so the text the gate cleared is not the text a consumer
+ * reads. The sigil is the discriminator, not the render/parse round-trip: the
+ * same line without an id still parses to `[]`.
+ *
+ * ⭐ So the row goes through the PARSER before it is judged — the oracle this
+ * module already uses for the empty-queue append. Trimming `text` would also
+ * close this one input; re-parsing closes the CLASS, because anything else the
+ * id-strip swallows arrives here already swallowed.
+ */
+function asWritten(item: QueueItem): QueueItem {
+  const parsed = queueItemsOf(parseWorkDoc(`## Queue\n${renderQueueLine(item)}\n`))[0];
+  if (!parsed) {
+    throw new QueueWriteError(
+      `the composed row does not parse as queue.v1 — refusing to write it: ${renderQueueLine(item)}`,
+    );
+  }
+  return parsed;
+}
+
+/**
+ * ⛔ THE TEXT FIELD LANDS IN ROW-PREFIX POSITION, WHICH IS STRUCTURAL, NOT BODY.
+ *
+ * `renderQueueLine` puts `text` immediately after the id — and the first thing
+ * after the id is MACHINE-READABLE. `leadingTagsOf` reads `**[key:value]**`
+ * there, `awaitingOf` reads `awaits`, and `next_unblocked` routes on it. So a
+ * caller passing `**[AWAITS:david]**` as prose changed ROUTING: measured end to
+ * end on the first version of this verb, `leadingTagsOf` returned
+ * `[{key:"awaits",value:"david"}]` and the item appeared on `awaitingDecision`.
+ *
+ * ⭐ THE GATE IS THE REAL PREDICATE, NOT A PATTERN. The first version of this
+ * module had no gate and its test used a regex proxy
+ * (`^- \[|⟨q-|\(P[123]\)`) which the tag grammar matches none of — so the
+ * suite was green while the premise was false. Asking `leadingTagsOf` the
+ * question it exists to answer means the gate cannot drift from the grammar: if
+ * the tag vocabulary widens, this widens with it, for free.
+ *
+ * Tags are not refused because they are dangerous to write — they are refused
+ * because they are not this verb's arguments. Adding them as TYPED arguments the
+ * verb renders itself is a separate, coherent change; letting them in through
+ * prose is the hand-editing this verb exists to replace.
+ */
+function assertNoLeadingTag(item: QueueItem): void {
+  const tags = leadingTagsOf(asWritten(item));
+  if (tags.length) {
+    const shown = tags.map((t) => `**[${t.key}:${t.value}]**`).join(" ");
+    throw new QueueWriteError(
+      `text must not begin with a row-prefix tag (${shown}): the position right after the id is ` +
+        `MACHINE-READABLE, so this would change routing rather than describe the item — ` +
+        `\`leadingTagsOf\` reads it and \`next_unblocked\` acts on it. ` +
+        `Markers are set by the seats that own them, not through an item's prose.`,
+    );
+  }
+}
+
+/*
+ * ⛔⛆⛆ THE TAG THAT DECIDES ROUTING HAD NO FIELD, SO THE STATE "BUILT, GREEN,
+ * STOPPED AT A HUMAN" WAS UNREACHABLE THROUGH THIS VERB — `⟨q-d920a123⟩`.
+ *
+ * `**[AWAITS:<who>]**` is READ by `next_unblocked` and reported on its own
+ * `awaitingDecision` axis, and the seam calls it "a FIELD set by whoever files the
+ * item". But this verb's schema was `op · id · text · priority` and nothing else, so
+ * the only route through it was to smuggle the tag inside `text` — which
+ * `assertNoLeadingTag` correctly refuses. ⭐ THE MARKER WAS NEVER WRITTEN AT THE
+ * TRANSITION NOT THROUGH FORGETFULNESS BUT BECAUSE THERE WAS NO MECHANISM: the aide
+ * hand-edited `⟨q-217cc151⟩`'s marker at 17:05 because the verb could not.
+ *
+ * The live instance is the cost: `next_unblocked` offered `⟨q-217cc151⟩` as `next`
+ * while that row was built, CI-green, gated FAIL and blocked on a publish only a
+ * human can perform.
+ *
+ * ⛔ AND THE REFUSAL STAYS EXACTLY AS STRONG. Tags arrive as TYPED FIELDS the verb
+ * renders itself; a tag inside `text` is still refused. The file already said this
+ * was the coherent change — "Adding them as TYPED arguments the verb renders itself
+ * is a separate, coherent change; letting them in through prose is the hand-editing
+ * this verb exists to replace." A field satisfiable by prose would BE the defect.
+ */
+
+/*
+ * ⭐ THE KEYS THIS VERB WILL SET, AND WHY THE LIST IS SHORT RATHER THAN OPEN.
+ *
+ * `awaits` and `sweep` are both READ by shipped code (`awaitingOf`, `sweepTagOf`),
+ * so setting them completes a loop that already exists. `undelivered` uses the same
+ * grammar and is deliberately NOT settable here: it is a fact about what is on the
+ * REGISTRY, derived by `check-undelivered-markers` from the publish record, and an
+ * agent asserting it by hand is how that marker would start lying. A caller that
+ * wants it is asking the wrong question of the wrong verb.
+ */
+const TAG_KEYS = ["awaits", "sweep"] as const;
+type TagKey = (typeof TAG_KEYS)[number];
+
+/**
+ * Split `item.text` into its carried tag run and the body after it.
+ *
+ * ⛔ THE SEAM IS THE ONLY LEXER, AND THAT IS THE POINT — NOT AN ECONOMY.
+ * `⟨q-1c4f8ae3⟩` is exactly this shape: one grammar, two parsers, different
+ * domains, both "working" (the check accepted `@scope/name@1.0.0`; the seam dropped
+ * it). So this does NOT re-implement `LEADING_TAG`. It asks `leadingTagsOf` where
+ * the run ends, by finding the SMALLEST boundary `i` such that
+ *
+ *   · the suffix from `i` carries NO tags, and
+ *   · the prefix up to `i`, with a tag-free sentinel appended so its run
+ *     terminates, carries ALL of them.
+ *
+ * Both conditions are needed. The first alone is satisfied by `i = 1` — cutting one
+ * `*` off `**[AWAITS:x]**` leaves a suffix that parses to `[]`, which would report
+ * the whole tag as body. The second alone is satisfied by `i = text.length` on a row
+ * whose BODY quotes a tag, which would report the whole body as tag run.
+ *
+ * ⭐ SMALLEST rather than largest, and the difference is a swallowed body: for
+ * `**[A:b]** body **[C:d]** x` the largest valid boundary is the end of the line —
+ * the prefix still carries exactly the one real tag and the empty suffix carries
+ * none — so a descending scan returns an EMPTY body. Measured before it was written.
+ */
+function splitLeadingTags(item: QueueItem): { tags: LeadingTag[]; body: string } {
+  const text = String(item.text);
+  const tagsOf = (t: string): LeadingTag[] => leadingTagsOf({ ...item, text: t });
+  const tags = tagsOf(text);
+  if (tags.length === 0) return { tags, body: text };
+  // Tag-free by construction: the grammar's key class is [a-z]+ and its value class
+  // admits no NUL, so this can never extend a run it is appended to.
+  const SENTINEL = "\u0000";
+  for (let i = 1; i <= text.length; i++) {
+    if (tagsOf(text.slice(i)).length !== 0) continue;
+    if (tagsOf(text.slice(0, i) + SENTINEL).length !== tags.length) continue;
+    // The grammar consumes the whitespace after `]**`; a second space would
+    // otherwise survive into the rendered line as a double space.
+    return { tags, body: text.slice(i).replace(/^\s+/, "") };
+  }
+  throw new QueueWriteError(
+    `could not locate the end of the tag run in ${JSON.stringify(text)} — refusing to guess a boundary, ` +
+      `because a wrong one would move part of the item's prose into machine-readable position`,
+  );
+}
+
+/**
+ * `item.text` with `changes` applied to its leading tags. `null` CLEARS a key.
+ *
+ * Existing tags are preserved and their order is kept, so setting `awaits` on a row
+ * that already carries `**[SWEEP:console]**` does not silently drop the sweep tag —
+ * the failure that would make this verb worse than the hand-edit it replaces.
+ */
+function retagged(
+  item: QueueItem,
+  changes: Partial<Record<TagKey, string | null>>,
+): { text: string; want: Map<string, string> } {
+  const { tags, body } = splitLeadingTags(item);
+  const map = new Map<string, string>(tags.map((t) => [t.key, t.value]));
+  for (const [k, v] of Object.entries(changes)) {
+    if (v === null) map.delete(k);
+    else if (v !== undefined) map.set(k, String(v));
+  }
+  const rendered = [...map].map(([k, v]) => `**[${k.toUpperCase()}:${v}]**`).join(" ");
+  return { text: rendered ? `${rendered} ${body}` : body, want: map };
+}
+
+/**
+ * ⛔ WHAT WAS INTENDED IS WHAT THE ROW WILL BE READ AS — asked of the parser, not assumed.
+ *
+ * `renderQueueLine` then the parser then `leadingTagsOf`, exactly the path a consumer
+ * takes. A value the grammar cannot express (a space, a `%`) composes into a token that
+ * does not match, and the oracle reports the tag as MISSING rather than this module
+ * deciding what the value class is — the charset stays the seam's, which is the lesson
+ * of `⟨q-1c4f8ae3⟩` where a reused grammar silently inherited a domain.
+ */
+function assertTagsAsRead(item: QueueItem, want: Map<string, string>): void {
+  const got = new Map(leadingTagsOf(asWritten(item)).map((t) => [t.key, t.value]));
+  const same =
+    got.size === want.size && [...want].every(([k, v]) => got.get(k) === String(v).toLowerCase());
+  if (!same) {
+    const show = (m: Map<string, string>) =>
+      m.size ? [...m].map(([k, v]) => `**[${k.toUpperCase()}:${v}]**`).join(" ") : "(none)";
+    throw new QueueWriteError(
+      `the tags this would WRITE are not the tags a consumer would READ — wanted ${show(want)}, ` +
+        `the row parses as ${show(got)}. Most likely a value the tag grammar cannot express; ` +
+        `the value class is the seam's and this verb will not widen it by guessing.`,
+    );
+  }
+}
+
+/**
+ * ⛔ THE ONE-LINE INVARIANT, ENFORCED AT THE BOUNDARY RATHER THAN DOCUMENTED.
+ *
+ * `queue.v1` is one line per item and a continuation is silently dropped by every
+ * consumer — measured at 83% of one item's content. An agent cannot be expected
+ * to know that, so a multi-line `text` is REFUSED here with the reason, instead
+ * of being written and quietly truncated later.
+ */
+function assertSingleLine(text: string): void {
+  if (/[\r\n]/.test(text)) {
+    throw new QueueWriteError(
+      "text must be a single line: queue.v1 is one line per item, and every parser drops a " +
+        "continuation line silently (measured: 83% of one item's content lost). " +
+        "Put detail in a file the row points at, or fold it into this line.",
+    );
+  }
+}
+
+/** The tags the row will be READ as, for the result. Read back, never echoed. */
+function tagsAsRead(item: QueueItem): Record<string, string> {
+  return Object.fromEntries(leadingTagsOf(asWritten(item)).map((t) => [t.key, t.value]));
+}
+
+/** A refusal the caller can act on, distinct from a stale-base refusal. */
+export class QueueWriteError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "QueueWriteError";
+  }
+}
+
+const readQueue = (repo: string): { text: string; doc: WorkDoc } => {
+  const p = path.join(repo, QUEUE_DOC);
+  if (!existsSync(p)) throw new QueueWriteError(`${QUEUE_DOC} does not exist under ${repo}`);
+  const text = readFileSync(p, "utf8");
+  return { text, doc: parseWorkDoc(text) };
+};
+
+/** The facts a caller needs back — never markdown. */
+type QueueWriteResult = {
+  ok: true;
+  op: "file" | "amend" | "reprioritise" | "retag";
+  id: string;
+  priority: (typeof PRIORITIES)[number];
+  /** The item's text as stored, so a caller can confirm what it said. */
+  text: string;
+  wrote: string[];
+  /** Ids this write stamped that the caller did not name — absorption, reported. */
+  stampedNotSupplied: string[];
+  /**
+   * The tags the written row PARSES as — read back through the seam, not echoed from
+   * the request, so a caller can see what a consumer will see.
+   */
+  tags: Record<string, string>;
+};
+
+export const queueWriteSchema = {
+  project: z.string().min(1),
+  repo: z.string().optional(),
+  op: z.enum(["file", "amend", "reprioritise", "retag"]),
+  /** Required for amend and reprioritise; never supplied for file (the verb mints it). */
+  id: z.string().optional(),
+  /** What the item is about. Prose, not markdown — a single line. */
+  text: z.string().min(1).optional(),
+  priority: z.enum(PRIORITIES).optional(),
+  /**
+   * Leading tags as FIELDS. `null` clears a key; an omitted key is left alone, so
+   * setting `awaits` never drops a `sweep` tag the row already carries.
+   */
+  tags: z
+    .object({
+      awaits: z.string().min(1).nullable().optional(),
+      sweep: z.string().min(1).nullable().optional(),
+    })
+    .optional(),
+};
+
+export async function queueWriteTool(args: {
+  project: string;
+  repo?: string;
+  op: "file" | "amend" | "reprioritise" | "retag";
+  id?: string;
+  text?: string;
+  priority?: (typeof PRIORITIES)[number];
+  tags?: Partial<Record<TagKey, string | null>>;
+}): Promise<QueueWriteResult | { ok: false; error: string; staleWrite?: unknown }> {
+  const repo = args.repo ?? process.cwd();
+  try {
+    // Refused at the boundary rather than rendered: an unknown key would compose a
+    // token the grammar accepts and no reader asks for — a tag nothing routes on,
+    // which is worse than an error because it LOOKS set.
+    for (const k of Object.keys(args.tags ?? {})) {
+      if (!(TAG_KEYS as readonly string[]).includes(k)) {
+        throw new QueueWriteError(
+          `unknown tag field '${k}' — this verb sets ${TAG_KEYS.join(", ")}. ` +
+            `\`undelivered\` is deliberately not settable here: it is derived from the publish ` +
+            `record by check-undelivered-markers, and asserting it by hand is how that marker starts lying.`,
+        );
+      }
+    }
+    const { text: original, doc } = readQueue(repo);
+    const items = queueItemsOf(doc);
+
+    // Locate the block the items live in, so a filed row joins the record model
+    // rather than being appended as text the parser has to re-discover.
+    const block = doc.blocks.find((b) => b.kind === "queue");
+
+    let target: QueueItem;
+    if (args.op === "file") {
+      if (args.id) throw new QueueWriteError("do not supply an id when filing: the verb mints and stamps it");
+      if (!args.text) throw new QueueWriteError("filing needs `text` — what the item is about");
+      if (!args.priority) throw new QueueWriteError(`filing needs \`priority\` — one of ${PRIORITIES.join(", ")}`);
+      assertSingleLine(args.text);
+      // Identity is the seam's to mint: derived from the text, then RECORDED, so
+      // the id stops depending on prose the moment it exists.
+      const seeded = parseWorkDoc(`## Queue\n- [ ] (${args.priority}) ${args.text}\n`);
+      const minted = queueItemsOf(seeded)[0];
+      if (!minted) throw new QueueWriteError("the composed row does not parse as queue.v1 — refusing to write it");
+      target = withRecordedId(minted);
+      // AFTER the id is stamped, never before: `assertNoLeadingTag` re-parses the
+      // rendered row, and the id-strip is the step that exposes a hidden tag.
+      assertNoLeadingTag(target);
+      // Tags AFTER the prose gate, never instead of it: `text` is still judged on its
+      // own, so the field form cannot be used to smuggle what the gate refuses.
+      if (args.tags && Object.keys(args.tags).length) {
+        const { text: next, want } = retagged(target, args.tags);
+        assertTagsAsRead({ ...target, text: next }, want);
+        assertSingleLine(next);
+        target.text = next;
+      }
+
+      if (block) {
+        block.items.push(target);
+      } else {
+        // AN EMPTY QUEUE SECTION HAS NO BLOCK, because blocks appear when items
+        // parse — and a fresh `groundwork init` queue is exactly that, so the
+        // FIRST filed row would otherwise be the one that cannot be filed.
+        //
+        // The seam's heading classifier is private and this module will not widen
+        // a shipped package's surface for its own convenience, so THE PARSER IS
+        // THE ORACLE instead of a guess: append the rendered line, re-parse, and
+        // accept only if the document now yields exactly this item as a queue
+        // item. If the append landed outside the queue section — a document whose
+        // queue is not last — the re-parse does not see it and this REFUSES
+        // rather than corrupting the file.
+        const candidate = `${original.replace(/\n*$/, "\n")}${renderQueueLine(target)}\n`;
+        const reparsed = parseWorkDoc(candidate);
+        const got = queueItemsOf(reparsed);
+        if (got.length !== items.length + 1 || !got.some((i) => i.id === target.id)) {
+          throw new QueueWriteError(
+            `${QUEUE_DOC} has no parsed queue block and appending did not produce one — the queue section is ` +
+              `probably not the last section in the file. Refusing to guess where the row goes; file the first ` +
+              `item by hand once, or move the queue section last.`,
+          );
+        }
+        const w0 = writeDoc(repo, QUEUE_DOC, reparsed, original);
+        return {
+          ok: true,
+          op: args.op,
+          id: target.id,
+          priority: args.priority,
+          text: target.text,
+          wrote: w0.written ? [QUEUE_DOC] : [],
+          stampedNotSupplied: w0.stamped.filter((id) => id !== target.id),
+          tags: tagsAsRead(target),
+        };
+      }
+    } else if (args.op === "retag") {
+      /*
+       * ⛔ THE WHOLE POINT: TAGS CHANGE WITHOUT THE TEXT BEING REWRITTEN.
+       *
+       * `amend` would have worked by making the caller resend the row's prose, and
+       * that is the defect in miniature — a verb that makes you restate 400 characters
+       * to set one field is a verb nobody uses at the transition, which is how the
+       * marker went unwritten in the first place. So `retag` REFUSES `text`: if it
+       * accepted it, the easy path would silently be "rewrite the row" again.
+       */
+      if (!args.id) throw new QueueWriteError("retag needs `id` — which item to tag");
+      if (args.text !== undefined) {
+        throw new QueueWriteError(
+          "retag does not take `text`: it exists so a tag can be set WITHOUT rewriting the item's prose. " +
+            "Use `amend` to change what the item says.",
+        );
+      }
+      if (args.priority !== undefined) {
+        throw new QueueWriteError("retag does not take `priority` — use `reprioritise`");
+      }
+      const changes = args.tags ?? {};
+      if (!Object.keys(changes).length) {
+        throw new QueueWriteError(
+          `retag needs \`tags\` — at least one of ${TAG_KEYS.join(", ")} (a value to set, or null to clear)`,
+        );
+      }
+      const found = items.find((i) => i.id === args.id);
+      if (!found) throw new QueueWriteError(`no queue item with id '${args.id}' in ${QUEUE_DOC}`);
+      target = found;
+      const { text: next, want } = retagged(target, changes);
+      // Composed on a COPY and judged BEFORE the item is mutated, so a refusal cannot
+      // leave a half-tagged row in the document about to be written.
+      assertTagsAsRead({ ...target, text: next }, want);
+      assertSingleLine(next);
+      target.text = next;
+    } else {
+      if (!args.id) throw new QueueWriteError(`${args.op} needs \`id\` — which item to change`);
+      const found = items.find((i) => i.id === args.id);
+      if (!found) throw new QueueWriteError(`no queue item with id '${args.id}' in ${QUEUE_DOC}`);
+      target = found;
+      if (args.op === "amend") {
+        if (!args.text) throw new QueueWriteError("amend needs `text`");
+        assertSingleLine(args.text);
+        // Amend has the same hole as file — the rewritten text occupies the same
+        // structural slot — so it gets the same gate. Applied to a COPY first, so
+        // a refusal cannot leave the in-memory item half-changed.
+        assertNoLeadingTag({ ...target, text: args.text });
+        target.text = args.text;
+      } else {
+        if (!args.priority) throw new QueueWriteError(`reprioritise needs \`priority\` — one of ${PRIORITIES.join(", ")}`);
+        target.priority = args.priority;
+        // A raw tag that disagreed with the parsed priority would re-render the
+        // old value; clearing it keeps the two from drifting apart.
+        delete (target as { priorityRaw?: string }).priorityRaw;
+      }
+    }
+
+    const w = writeDoc(repo, QUEUE_DOC, doc, original);
+    return {
+      ok: true,
+      op: args.op,
+      id: target.id,
+      priority: (target.priority ?? args.priority) as (typeof PRIORITIES)[number],
+      text: target.text,
+      wrote: w.written ? [QUEUE_DOC] : [],
+      stampedNotSupplied: w.stamped.filter((id) => id !== target.id),
+      tags: tagsAsRead(target),
+    };
+  } catch (e) {
+    if (e instanceof StaleWriteError) {
+      return { ok: false, error: e.message, staleWrite: { doc: e.rel, drift: e.detail, alreadyWritten: e.alreadyWritten } };
+    }
+    if (e instanceof QueueWriteError) return { ok: false, error: e.message };
+    throw e;
+  }
+}