agent-coord-mcp 0.26.18 → 0.26.19

package/dist/tools/away.js

@@ -0,0 +1,285 @@
+/*
+ * `coord_away` — DAVID IS AWAY AND THE AIDE LEADS.
+ *
+ * REDEFINED (David, 2026-08-30). The verb used to mean "the coordinator stepped
+ * out and a duty officer keeps its seat warm". That meaning is RETIRED, not
+ * deprecated: same skill label, one meaning. A verb with two meanings is read
+ * as whichever one the reader already had in mind, and the two differ on who
+ * holds authority — the most expensive thing to be ambiguous about.
+ *
+ * WHAT IT NOW MEANS: David is away, and the aide LEADS in his absence. That is
+ * a grant of DECISION authority, not of execution authority, and the boundary
+ * is the feature:
+ *
+ *   DECIDES  planning · priority · queue curation · roadmap · canon · releases
+ *            under standing publish authorisation.
+ *   NEVER    merges, gates, or takes a code lane. Unchanged by the grant — a
+ *            lead is not a second worker, and the aide's nevers are what keep
+ *            the gate non-author.
+ *   PARKS    licence · funding · public-vs-private · credentials · anything
+ *            altering scope or authority · destructive machine actions.
+ *
+ * WHY PARK RATHER THAN REFUSE-AND-FORGET: a parked decision is one David
+ * returns to. The whole point of leading in an absence is that the absence ends,
+ * and the fleet should hand back a DIFF rather than a transcript — which is why
+ * `decisionLog` is required to turn this on rather than being a nice-to-have.
+ *
+ * THE PRECONDITION IS MEASURED COVERAGE, NOT A RUN. Going away is a promise
+ * that the fleet is observed while nobody is watching, and the fleet was
+ * measured making that promise with a stall clock that had been stopped for
+ * eight hours — and then, once started, reporting `checked 3 · measurable 0`.
+ * "The clock ran" and "the fleet is observed" are different facts. So the
+ * precondition asks what the clock could actually SEE, and going away blind is
+ * a deliberate, recorded act rather than a silent default.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { ROOT } from "../store.js";
+import { stallCheckTool } from "./stall.js";
+const awayFile = () => path.join(ROOT, "coord-away.json");
+/**
+ * WHAT THE LEAD MAY NOT DO, enforced rather than trusted to a card line.
+ *
+ * ALLOWLIST FOR THE OLD MEANING, DENYLIST FOR THIS ONE — and the asymmetry is
+ * deliberate rather than a relaxation. A duty officer's grant was NARROW ("keep
+ * claimed work moving"), so absence had to mean refusal or every unlisted tool
+ * was a silent grant. A lead's grant is WIDE by design: it decides planning,
+ * priority, curation, roadmap, canon and releases, which is most of the bus. An
+ * allowlist over a wide grant would have to enumerate nearly every tool, and the
+ * one someone forgets would refuse legitimate work in the middle of an absence —
+ * failing in the direction that leaves the fleet stuck with nobody to ask.
+ *
+ * What is refused is small, closed, and named for its reason: the aide's
+ * `never merges / never gates` rule. That rule does not widen when David leaves;
+ * it is load-bearing precisely because the gate must stay non-author.
+ */
+export const LEAD_REFUSED = {
+    merge: "merging is the gate acting. The aide never gates, and leading in David's absence does not change who may — a lead that merges is an author gating its own plan.",
+    land: "`land` writes docs/DONE.md, which is the coordinator's file. Leading does not transfer file ownership; ask the coordinator to record it.",
+};
+/**
+ * Decisions that WAIT for David. Not refused because they are dangerous to
+ * execute — refused because they are not the aide's to make, and an absence is
+ * not a transfer of that authority.
+ */
+export const PARKED_CATEGORIES = [
+    "licence",
+    "funding",
+    "public-vs-private",
+    "credentials",
+    "anything altering scope or authority",
+    "destructive machine actions",
+];
+export function readAway() {
+    const f = awayFile();
+    if (!existsSync(f))
+        return {};
+    try {
+        return JSON.parse(readFileSync(f, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeAway(state) {
+    mkdirSync(ROOT, { recursive: true });
+    writeFileSync(awayFile(), `${JSON.stringify(state, null, 2)}\n`);
+}
+/**
+ * The refusal the LEAD gets, or null if the call is allowed.
+ *
+ * Only the lead is constrained, and only on the two verbs above. Everyone
+ * else's lane is untouched: `coord_away` is not a freeze on the project, and a
+ * worker whose tools stopped working because David went out would simply stop
+ * calling them.
+ */
+export function awayRefusal(state, agentId, tool) {
+    if (!agentId)
+        return null;
+    const held = Object.values(state).find((s) => s.on && s.leadId === agentId);
+    if (!held)
+        return null;
+    const why = LEAD_REFUSED[tool];
+    if (!why)
+        return null;
+    return (`'${tool}' is refused while you LEAD on '${held.project}' in David's absence: ${why} ` +
+        `Leading grants DECISION authority — planning, priority, curation, roadmap, canon, releases — not execution authority. ` +
+        `If this genuinely needs doing, it needs the coordinator, or David back. Record it in ${held.decisionLog} either way.`);
+}
+/**
+ * RETIRED WITH THE OLD MEANING. Kept as a no-op so the call site in
+ * `registerTool` keeps compiling and the retirement is visible where the guard
+ * used to be, rather than as an absence someone re-derives later.
+ *
+ * Under the old meaning the coordinator was the one away, so a second
+ * coordinator joining was a fleet-shape change made behind its back. Under this
+ * one the coordinator is present and working, and blocking a second coordinator
+ * while DAVID is out would refuse a legitimate handoff at exactly the moment
+ * nobody can approve it.
+ *
+ * RECORDED GAP, deliberately not solved here: retiring the duty-officer meaning
+ * leaves COORDINATOR absence uncovered. If the coordinator goes down while David
+ * is away, nothing covers the seat. That is a decision, not an oversight — it is
+ * named so the next reader finds a choice rather than a hole.
+ */
+export function secondCoordinatorRefusal(_state, _agentId, _roleId) {
+    return null;
+}
+export const coordAwaySchema = {
+    project: z.string().min(1),
+    // Omitted → a QUERY: report current state and mutate nothing (q-1abbbdbf).
+    // `/coord-away` used to be a bare toggle read by a human deciding which
+    // direction to call it — the incident this fixes is David typing it
+    // meaning ARM while it was already armed, and the aide independently
+    // reading the same typed command as RELEASE, with no state visible to
+    // either of them before acting. State-it-aloud-first only works if there
+    // is a state to read that does not itself flip the switch.
+    on: z.boolean().optional(),
+    /** The agent leading in David's absence — the aide. */
+    leadId: z.string().optional(),
+    /** Repo-relative path where decisions taken during the absence are written. */
+    decisionLog: z.string().optional(),
+    until: z.string().optional(),
+    /** Repo to measure stall coverage against. */
+    repo: z.string().optional(),
+    /** Turn it on knowing the fleet is unobserved. Recorded in the state. */
+    acknowledgeBlindFleet: z.boolean().optional(),
+    /** Who is calling — the lead may turn it on and release it. */
+    agentId: z.string().optional(),
+};
+async function measureCoverage(repo) {
+    if (!repo)
+        return null;
+    try {
+        const r = (await stallCheckTool({ repo }));
+        if (!r?.ok)
+            return null;
+        return { checked: r.checked ?? 0, measurable: r.measurable ?? 0, blind: r.blind ?? [], at: new Date().toISOString() };
+    }
+    catch {
+        return null;
+    }
+}
+export async function coordAwayTool(args) {
+    const state = readAway();
+    const prior = state[args.project];
+    // QUERY — `on` omitted. Reads, never writes: no coverage measurement, no
+    // refusal, no side effect. This is the call a card makes to state current
+    // status aloud BEFORE deciding which direction to arm/release, so the
+    // decision is never made blind the way it was on 2026-08-30/31.
+    if (args.on === undefined) {
+        if (!prior?.on) {
+            return {
+                ok: true,
+                query: true,
+                project: args.project,
+                armed: false,
+                state: prior ?? null,
+                summary: prior
+                    ? `'${args.project}' is NOT armed — last released ${prior.at}.`
+                    : `'${args.project}' is NOT armed — never armed.`,
+            };
+        }
+        return {
+            ok: true,
+            query: true,
+            project: args.project,
+            armed: true,
+            state: prior,
+            summary: `'${args.project}' is ARMED — '${prior.leadId}' leads since ${prior.at}` +
+                `${prior.until ? ` until ${prior.until}` : ""}. ` +
+                `Coverage ${prior.coverage.measurable}/${prior.coverage.checked}` +
+                `${prior.blindAcknowledged ? " (ACKNOWLEDGED BLIND)" : ""}. ` +
+                `Decisions logged to ${prior.decisionLog}.`,
+        };
+    }
+    if (args.on) {
+        // A LEAD WITH NO NAME IS AN ABSENCE DESCRIBED AS COVERED, which is strictly
+        // worse than an absence everyone can see is uncovered.
+        if (!args.leadId) {
+            return { ok: false, error: `coord-away ON requires a leadId — the agent leading in David's absence. Turning it on without naming one reports the fleet as led while leaving it unled.` };
+        }
+        if (!args.decisionLog) {
+            return {
+                ok: false,
+                error: `coord-away ON requires a decisionLog path. The point of leading through an absence is that the absence ENDS: ` +
+                    `David should return to a diff he can read, not a transcript he has to reconstruct. A log promised at the start ` +
+                    `and written at the end is a log nobody wrote.`,
+            };
+        }
+        if (prior?.on) {
+            return { ok: false, error: `coord-away is already ON for '${args.project}' — '${prior.leadId}' leads since ${prior.at}. Release it before re-arming.` };
+        }
+        // THE PRECONDITION: what could the clock actually SEE?
+        const coverage = await measureCoverage(args.repo);
+        if (!coverage) {
+            return {
+                ok: false,
+                error: `cannot measure stall coverage for '${args.project}'${args.repo ? "" : " — pass 'repo'"}. ` +
+                    `Going away is a promise that the fleet is watched while nobody is watching, and an UNMEASURED promise ` +
+                    `is the one this verb exists to stop making. Fix the measurement, or pass acknowledgeBlindFleet:true to ` +
+                    `record that the promise is being made anyway.`,
+            };
+        }
+        // `checked > 0` MATTERS: an empty board is an IDLE fleet, not a blind one.
+        // Without it, arming while nothing is in flight refuses with "the clock
+        // covers 0 of 0" — a refusal that reads as a fleet nobody can see when in
+        // fact there is nothing to see, and the only way past it would be to
+        // acknowledge a blindness that does not exist.
+        if (coverage.checked > 0 && coverage.measurable === 0 && !args.acknowledgeBlindFleet) {
+            return {
+                ok: false,
+                error: `REFUSING: the stall clock covers ${coverage.measurable} of ${coverage.checked} in-flight row(s). ` +
+                    `It would RUN and see nothing${coverage.blind.length ? ` — blind on: ${coverage.blind.join(", ")}` : ""}. ` +
+                    `"The clock ran" and "the fleet is observed" are different facts, and this verb must not treat the first as the second. ` +
+                    `The usual cause is a board 'Branch · Worktree' cell holding a PATH rather than a branch ref: a path resolves for ` +
+                    `git and measures the wrong thing, so the check reports it unmeasurable rather than guessing. Fix those cells and ` +
+                    `coverage returns. If you mean to go anyway, pass acknowledgeBlindFleet:true — it is recorded in the state and in the announcement.`,
+            };
+        }
+        state[args.project] = {
+            on: true,
+            project: args.project,
+            away: "david",
+            leadId: args.leadId,
+            until: args.until,
+            at: new Date().toISOString(),
+            decisionLog: args.decisionLog,
+            coverage,
+            ...(coverage.checked > 0 && coverage.measurable === 0 ? { blindAcknowledged: true } : {}),
+        };
+        writeAway(state);
+        return {
+            ok: true,
+            state: state[args.project],
+            refused: LEAD_REFUSED,
+            parked: PARKED_CATEGORIES,
+            // A confirmation naming the transition, not just the imperative
+            // direction (q-1abbbdbf) — "ON" and "already ON" read the same at a
+            // glance; "OFF → ARMED" cannot be misread as a no-op or a repeat.
+            transition: "OFF → ARMED",
+            announce: `OFF → ARMED. AGENT_ACTION: coord-away ON — David is away${args.until ? ` until ${args.until}` : ""}; '${args.leadId}' LEADS. ` +
+                `Decides: planning · priority · curation · roadmap · canon · releases under standing authorisation. ` +
+                `Never: merges, gates, or takes a code lane. Parks for David: ${PARKED_CATEGORIES.join(" · ")}. ` +
+                `Decisions logged to ${args.decisionLog}. ` +
+                `Stall coverage ${coverage.measurable}/${coverage.checked}${coverage.checked > 0 && coverage.measurable === 0 ? " — ACKNOWLEDGED BLIND: the clock runs and sees nothing" : ""}.`,
+        };
+    }
+    if (!prior?.on)
+        return { ok: false, error: `coord-away is not on for '${args.project}' — nothing to release.` };
+    // RELEASE IS OBSERVING THAT DAVID IS BACK, not lifting a limit on yourself —
+    // which is why the lead may do it and a duty officer could not. The parked
+    // decisions are NOT unparked by it: they were never the lead's to make, and
+    // release does not retroactively authorise one.
+    state[args.project] = { ...prior, on: false, at: new Date().toISOString() };
+    writeAway(state);
+    return {
+        ok: true,
+        state: state[args.project],
+        transition: "ARMED → RELEASED",
+        announce: `ARMED → RELEASED. AGENT_ACTION: coord-away RELEASED on '${args.project}' — David is back; '${prior.leadId}' stands down as lead. ` +
+            `Anything parked during the absence is still parked: release does not authorise it. Decisions taken: ${prior.decisionLog}.`,
+    };
+}
+//# sourceMappingURL=away.js.map

package/dist/tools/away.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"away.js","sourceRoot":"","sources":["../../src/tools/away.ts"],"names":[],"mappings":"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"}

package/dist/tools/board-ref.js

@@ -0,0 +1,208 @@
+/*
+ * IS THIS BOARD CELL'S REF A PER-AGENT ACTIVITY SIGNAL?
+ *
+ * One classifier, used by the CHECKER that reads the cell and the VERB that
+ * writes it. A rule enforced at the read and not the write is a rule the write
+ * defeats: `claim` writes these rows, so if a bad ref is refusable by
+ * `stall_check` and writable by `claim`, the verb the fleet is being pushed
+ * toward becomes the thing that manufactures the bad row.
+ *
+ * FOUR WAYS THIS ONE CELL HAS BEEN WRONG, all measured on this fleet:
+ *
+ *   `docs/*`                     a PATH — refused today, correctly
+ *   `main`                       a SHARED ref — resolved, and reported the
+ *                                whole fleet's activity as one agent's, so the
+ *                                row could never stall
+ *   `worker-3/task13-…`          LOCAL-ONLY — resolved for its author and for
+ *                                nobody else, so the same board read
+ *                                differently from two checkouts
+ *   `worker-1/task16-3-…`        MERGED — resolves everywhere and is FROZEN by
+ *                                construction, so it reports an ever-growing
+ *                                stall on a lane that is finished
+ *
+ * THREE OF THOSE FOUR RESOLVED CLEANLY. So the test cannot be "does it
+ * resolve" — that check passed on every bad case except the path. The property
+ * is narrower and it is the one thing all four violate:
+ *
+ *   THE CELL MUST NAME A REF WHOSE MOVEMENT IS THIS AGENT'S WORK.
+ *
+ * Which decomposes into three questions git can actually answer:
+ *
+ *   scoped    does the ref name begin with this agent's id? That is the ONLY
+ *             per-agent signal this repo carries. Author cannot serve: measured
+ *             on 60 commits of `origin/main`, every one is authored "David
+ *             Balzan", so an `--author` filter would match every agent on every
+ *             ref forever WHILE LOOKING SCOPED.
+ *   shared    is it resolvable from ANY checkout, not just the one that happens
+ *             to have fetched it? That means the remote-tracking form.
+ *   live      is it still ahead of the base? A merged branch's ref never moves
+ *             again, so measuring it produces a number that only grows.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO: guess. Every rejection is reported with
+ * the reason and the population it judged, and an UNPUSHED branch is called
+ * unpushed rather than stalled — a freshly claimed lane has no shared evidence
+ * yet, and saying "stalled" there would be the manufactured-narrowing error
+ * pointed at a new lane.
+ */
+import { execFileSync } from "node:child_process";
+const git = (repo, args) => {
+    try {
+        return execFileSync("git", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return null;
+    }
+};
+const resolves = (repo, ref) => !!git(repo, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+// Task 5.3/22.1's confirmation half: `docs/*` — a real historical cell value
+// — is a GLOB, and `git check-ref-format` refuses it as a branch name (a `*`
+// is not legal in a ref). A plain path like `docs/QUEUE.md` is, frustratingly,
+// ALSO a syntactically valid ref name (slashes and dots are both legal), so
+// this catches the glob shape precisely and does not claim to catch every
+// path — an honest partial fix is the property this task's own title asks
+// for ("every classifier can say I cannot tell"), not a heuristic that
+// pretends to be exhaustive.
+// Pure syntax check — never needs to run INSIDE a repo, so no `cwd` (unlike
+// every other helper here, which resolves refs against `repo`'s history).
+const isSyntacticallyValidRef = (name) => {
+    try {
+        execFileSync("git", ["check-ref-format", "--branch", name], { stdio: ["ignore", "pipe", "ignore"] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** The `\`ref\`` inside a `Branch · Worktree` cell, or "". */
+export function refInCell(cell) {
+    return (String(cell ?? "").match(/`([^`]+)`/)?.[1] ?? "").trim();
+}
+/** The remote-tracking form a board cell should name for `branch`. */
+export const boardRefFor = (branch) => (branch.startsWith("origin/") ? branch : `origin/${branch}`);
+/**
+ * Classify one cell for one agent.
+ *
+ * `base` is the ref a merged branch would be contained in — `origin/main` by
+ * convention, passed rather than assumed so a consumer fleet on another default
+ * branch is not silently misjudged.
+ */
+export function classifyBoardRef(repo, agentId, cell, base = "origin/main") {
+    const raw = refInCell(cell);
+    if (!raw)
+        return { kind: "empty", why: "no ref in the Branch · Worktree cell" };
+    const bare = raw.replace(/^origin\//, "");
+    // Task 5.3/22.1: CHECKED FIRST AND UNCONDITIONALLY — the original defect
+    // (`docs/*`) was previously only caught in a repo with NO origin remote at
+    // all (further down); confirmed live that in a repo WITH an origin — the
+    // normal case for every worktree this fleet actually runs — the same
+    // value fell through to the "unpushed" branch instead and was reported as
+    // "the branch has not been pushed", which is a confidently WRONG diagnosis
+    // for a path. `git check-ref-format` answers "could this even syntactically
+    // be a branch name" without touching the repo's history at all, so a glob
+    // is caught regardless of what else is true about this checkout.
+    if (!isSyntacticallyValidRef(bare)) {
+        return { kind: "path", why: `'${raw}' is not a syntactically valid branch name — it is a path or glob` };
+    }
+    // A SHARED REF FIRST, because `main` resolves and would otherwise be measured.
+    // Named explicitly rather than inferred from scoping, so the reason a reader
+    // gets is the real one.
+    const shared = new Set(["main", "master", "develop", "trunk", "HEAD"]);
+    if (shared.has(bare)) {
+        return {
+            kind: "shared",
+            why: `'${raw}' is a SHARED branch — every agent merges into it, so its movement is the fleet's activity and not '${agentId}'s. ` +
+                `A row pointing here can never stall, which is a manufactured green rather than a measurement.`,
+        };
+    }
+    // SCOPED BY NAME — but only refusing a ref that belongs to a DIFFERENT agent,
+    // never one that is merely unconventional.
+    //
+    // Authorship cannot carry ownership here (every commit in this repo is
+    // authored by the same person, so `--author` would match every agent on every
+    // ref while looking scoped), which leaves the branch-naming convention
+    // `<agentId>/<slice>`. But REQUIRING that convention would make a repo that
+    // does not use it universally blind — and a narrowing that disables the check
+    // everywhere is worse than the defect it fixes. So a plain `feature-x` is
+    // allowed and `<someone-else>/x` is refused: the second is positively
+    // someone else's work, the first is only unlabelled.
+    const owner = bare.includes("/") ? bare.slice(0, bare.indexOf("/")) : null;
+    if (owner && owner !== agentId && /^[\w.-]+-(worker|aide|qa|ci|coordinator)(-\d+)?$/.test(owner)) {
+        return {
+            kind: "unscoped",
+            why: `'${raw}' is scoped to '${owner}', not '${agentId}' — its movement is that agent's work. ` +
+                `A per-agent signal needs a ref only this agent writes, and the branch name is the only ownership marker this repo carries.`,
+        };
+    }
+    const remote = `origin/${bare}`;
+    const remoteResolves = resolves(repo, remote);
+    const localResolves = resolves(repo, bare);
+    // NO SHARED FORM CAN EXIST, so the local ref is the best evidence there is.
+    // Without this a repo with no `origin` remote would report every row
+    // unmeasurable forever — the check disabled everywhere by a rule meant to
+    // make it honest. Preferring the shared form is right; requiring one that
+    // cannot exist is not.
+    if (!remoteResolves && !resolves(repo, "origin/HEAD") && git(repo, ["remote", "get-url", "origin"]) === null) {
+        if (!localResolves) {
+            return { kind: "path", why: `'${raw}' does not resolve as a git ref in a repo with no remote — it is a path or glob` };
+        }
+        return { kind: "measurable", ref: bare };
+    }
+    if (!remoteResolves) {
+        // Local-only vs never-pushed are different facts and only one is a defect
+        // in the CELL. Both are unmeasurable, and neither is a stall.
+        if (localResolves) {
+            return {
+                kind: "local-only",
+                why: `'${raw}' resolves in THIS checkout and not on the remote, so the same board reads differently from another checkout — ` +
+                    `whether it is measurable depends on who last ran \`git fetch\`, which is a property of the reader rather than of the work.`,
+            };
+        }
+        // Task 5.3/22.2's fourth cause: "a pushed branch absent from this
+        // checkout" is NOT the same fact as "never pushed", and this check has
+        // no way to tell them apart without a network call it deliberately does
+        // not make (every other verdict here is a local git op only — adding
+        // one here would trade the offline property for one more cause). SAYING
+        // SO is the fix Task 22's own title asks for: a classifier that names
+        // an ABSENCE of evidence as a specific, confident cause is the exact
+        // shape "it is a path or glob" was wrong in — just moved one branch
+        // over. `'${remote}' does not exist` is the one fact this DOES know;
+        // everything past it is now framed as what it cannot distinguish rather
+        // than a guess dressed as a finding.
+        return {
+            kind: "unpushed",
+            why: `'${remote}' does not resolve in THIS checkout — either the branch has never been pushed, or it WAS pushed and this ` +
+                `checkout's remote-tracking ref is simply stale (nobody has run \`git fetch\` here since). Cannot distinguish the two ` +
+                `without asking the remote, which this check deliberately does not do. Either way there is no LOCAL evidence of ` +
+                `activity, so it is not scored as a stall.`,
+        };
+    }
+    // MERGED IS FROZEN. Its ref can never move again, so any age computed from it
+    // only grows — an ever-worsening stall on a lane that is finished.
+    //
+    // `--is-ancestor` ALONE CANNOT SEE IT, and this fleet is the case that proves
+    // it: we SQUASH-merge, so the branch's commits never become ancestors of the
+    // base. Measured on a branch I knew was merged — `--is-ancestor` said NO
+    // while the work was plainly on main. A merged-detector that cannot detect
+    // this repo's own merge strategy is inert, which is worse than absent because
+    // it reads as covered.
+    //
+    // `git cherry` compares PATCH IDS, so a squashed single-commit branch reports
+    // `-` (already upstream). It is not complete either — squashing several
+    // commits into one changes the patch id — so BOTH tests run and either one
+    // answering yes is enough. Neither is asked to be sufficient alone.
+    if (resolves(repo, base)) {
+        const ancestor = git(repo, ["merge-base", "--is-ancestor", remote, base]) !== null;
+        const cherry = git(repo, ["cherry", base, remote]);
+        const allUpstream = cherry !== null && cherry.length > 0 && cherry.split("\n").every((l) => l.trim().startsWith("-"));
+        if (ancestor || allUpstream) {
+            return {
+                kind: "merged",
+                why: `'${remote}' has already landed in ${base} (${ancestor ? "an ancestor" : "every commit's patch is upstream — a squash merge"}) — ` +
+                    `so this ref is FROZEN and can never move again. ` +
+                    `Measuring it reports a stall that grows forever on a finished lane. The row needs the agent's current slice, or an idle marker.`,
+            };
+        }
+    }
+    return { kind: "measurable", ref: remote };
+}
+//# sourceMappingURL=board-ref.js.map

package/dist/tools/board-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-ref.js","sourceRoot":"","sources":["../../src/tools/board-ref.ts"],"names":[],"mappings":"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"}

package/dist/tools/event-kinds.js

@@ -0,0 +1,39 @@
+/*
+ * THE KIND REGISTRY IS THE SINGLE SOURCE, AND THAT IS TASK 9.2.
+ *
+ * `SubKind` used to be a hand-written union next to a hand-written zod enum next
+ * to an emitter that covered one of the four. Nothing connected them, so a kind
+ * could be offered for subscription while nothing could ever emit it — and
+ * `list_subscriptions` would report its permanent `never evaluated` forever,
+ * honestly and uselessly.
+ *
+ * Now the union, the wire enum, and the emitter set are all derived from THIS
+ * object. A kind cannot be offered without an emitter because the enum is
+ * generated from the emitters; `test/record-events.test.mjs` closes the other
+ * half by asserting each kind actually fires. Unsatisfiable BY CONSTRUCTION,
+ * rather than by a reviewer noticing.
+ */
+export const EVENT_KINDS = {
+    item: {
+        record: "docs/QUEUE.md + docs/DONE.md",
+        what: "a queue item closed — it left QUEUE.md and a DONE.md entry appeared in the same commit",
+        targetIs: "the queue item id",
+    },
+    pr: {
+        record: "docs/DONE.md",
+        what: "a PR recorded in the completion log",
+        targetIs: "the PR ref, e.g. owner/repo#163",
+    },
+    task: {
+        record: "docs/phases/**/PHASE*_TASKS.md",
+        what: "a phase task checkbox newly ticked",
+        targetIs: "the task key, e.g. 5:12.1",
+    },
+    phase: {
+        record: "docs/phases/**/PHASE*_TASKS.md",
+        what: "the last open checkbox in a phase document ticked",
+        targetIs: "the phase number, e.g. 5",
+    },
+};
+export const EVENT_KIND_IDS = Object.keys(EVENT_KINDS);
+//# sourceMappingURL=event-kinds.js.map

package/dist/tools/event-kinds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-kinds.js","sourceRoot":"","sources":["../../src/tools/event-kinds.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE;QACJ,MAAM,EAAE,8BAA8B;QACtC,IAAI,EAAE,wFAAwF;QAC9F,QAAQ,EAAE,mBAAmB;KAC9B;IACD,EAAE,EAAE;QACF,MAAM,EAAE,cAAc;QACtB,IAAI,EAAE,qCAAqC;QAC3C,QAAQ,EAAE,iCAAiC;KAC5C;IACD,IAAI,EAAE;QACJ,MAAM,EAAE,gCAAgC;QACxC,IAAI,EAAE,oCAAoC;QAC1C,QAAQ,EAAE,2BAA2B;KACtC;IACD,KAAK,EAAE;QACL,MAAM,EAAE,gCAAgC;QACxC,IAAI,EAAE,mDAAmD;QACzD,QAAQ,EAAE,0BAA0B;KACrC;CACO,CAAC;AAEX,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAA4B,CAAC"}