@floh-solutions/pharos-cli 0.23.0 → 0.24.0

package/dist/commands/issue.js

@@ -0,0 +1,2188 @@
+import { addHyperlink, addParent, setField, setMarkdown, } from "@floh-solutions/ado-core";
+import { GitHubNotFoundError, PullRequestNotAnIssueError, assertIssueCoordinate, composeLinkComment, formatIssueCoordinate, isPharosAuthored, isTwoSided, issueUrl, linksFromComments, linksFromHyperlinks, mergeLinks, normalizeRepo, parseRepo, } from "@floh-solutions/gh-core";
+import { DEFAULT_WRITE_BUDGET } from "../budget.js";
+import { ADOPT_GUARD_LIMIT, READ_CONCURRENCY, WRITES_PER_ADOPTION, adoptGuardWiql, backfillCandidates, claimsOn, driftWiql, finishedStates, inBatches, isFinished, judgeLink, linkedNumbersIn, linksOnWorkItems, looksLikeWiqlRejection, reposOf, tallyDrift, terminalStateFor, } from "../issue-scan.js";
+import { CliError, emit, emitText, failureOf, refusal, usageError, } from "../output.js";
+import { approve } from "../session.js";
+/**
+ * `pharos issue` — the cross-platform **edge**, and only the edge.
+ *
+ * ## Why there are three verbs here and not thirty
+ *
+ * **Do not rebuild `gh`** (plan §8). The agent already has it, it is better than
+ * anything here would be, and a second GitHub CLI is the "second implementation
+ * that drifts" failure `AGENTS.md` names three separate times. There is no
+ * `pharos issue list`, no `issue view`, no `issue close`: reading and writing an
+ * issue is `gh`'s job, reading and writing a work item is the other twenty-seven
+ * verbs' job. What neither can do is join them, and that is all this is.
+ *
+ * | verb | what only this can do |
+ * |---|---|
+ * | `adopt` | create the work item AND write both ends of the link, in that order, idempotently |
+ * | `link`  | join an existing pair, or finish a join that half-happened |
+ * | `say`   | one message, two audiences — the full explanation to GitHub, a summary and the comment's URL to Azure DevOps |
+ * | `trail` | the whole trail from **either** end, with the evidence for each half |
+ *
+ * `say` is the one that could be mistaken for `gh issue comment` plus `pharos
+ * comment add`, and it is not: those two write the same words twice to two
+ * audiences with different access, and neither of them knows the other
+ * happened. The asymmetry is the feature (§8) — see {@link runSay}.
+ *
+ * ## The link is three layers, and this writes two of them
+ *
+ * Plan §6, in order of durability:
+ *
+ * 1. **Durable and human-visible.** On Azure DevOps a `Hyperlink` relation to
+ *    the issue URL. Measured, not chosen: `_apis/githubconnections` answers 401
+ *    on Pharos's PAT scopes while a control WIQL call answers 200 with the same
+ *    token, so the connection id a native `vstfs:///GitHub/Issue/…` artifact
+ *    link needs cannot be read at all (§2). On GitHub, one Pharos comment
+ *    carrying `AB#<id>` — free official linking wherever the Azure Boards app
+ *    happens to be installed, harmless text where it is not.
+ * 2. **Machine-readable.** The `<!-- pharos:v1 … -->` trailer inside that same
+ *    comment. **In a comment, never the issue body**: editing a reporter's body
+ *    collides with them, is rude on a public repo, and needs write access we may
+ *    not have on a community issue.
+ * 3. **Fast.** A local join table, rebuilt from 1 and 2. This CLI has none — it
+ *    reads the durable layers every time, which is why it needs no state on disk
+ *    and cannot be stale.
+ *
+ * Both layers are composed by `gh-core`'s {@link composeLinkComment} and read
+ * back by its {@link linksFromComments} / {@link linksFromHyperlinks}. Nothing
+ * here parses or formats a marker. The grammar is a **shared contract** with a
+ * Swift port that tests against the same fixture file, and a second parser here
+ * would be the drift that fixture exists to prevent.
+ *
+ * ## The write order, and the one failure it leaves behind
+ *
+ * Azure DevOps first, GitHub second — in `adopt` because the work item id does
+ * not exist until the create lands, and in `link` for the same order so there is
+ * **one** recovery path rather than two. So the failure this can leave is always
+ * the same shape: the ADO end written, the GitHub end not. `pharos issue link
+ * <repo#n> <id>` completes exactly that, and `adopt` reports the created id and
+ * that command when the comment fails rather than only reporting the error — a
+ * work item nobody can name is worse than a failed call.
+ *
+ * ## What "already linked" means, and the three places it is asked
+ *
+ * The GitHub comment is the index, and it is the *first* thing read: an issue
+ * carrying a marker is already adopted, `adopt` returns the work item it names,
+ * exit 0, nothing written. That is the property an agent that retries depends
+ * on.
+ *
+ * **It is not sufficient on its own, and that cost a real duplicate.** In the
+ * half-linked state — the work item created, the comment not — the marker was
+ * never posted, so the index is silent about a work item that already exists.
+ * A retry there used to create a *second* one: its own id, its own place in a
+ * sprint, its own notifications, on a client's board, and nothing in this app
+ * removes it. That state is exactly the one a retry follows, because it is the
+ * one that just returned an error.
+ *
+ * So before creating anything, two more questions are asked, cheapest first,
+ * and either of them makes `adopt` **refuse** and hand over the same
+ * `pharos issue link` command the failure itself carried:
+ *
+ * 1. **This machine.** `half-link.ts` records an adoption between the create
+ *    and the comment, and removes it when the comment lands. Local, no round
+ *    trip, and the only one of the three that can see a work item created
+ *    seconds ago — WIQL answers from an index that lags a write by moments,
+ *    which is precisely the window a retry arrives in. An entry is *verified*
+ *    against Azure DevOps before it is believed, so a work item that was since
+ *    deleted cannot wedge a legitimate adoption.
+ * 2. **The board**, for everything the first cannot see: a retry from another
+ *    machine, another checkout, or after the journal was lost. Azure DevOps has
+ *    no query over relation URLs, so this narrows on `[System.HyperLinkCount]`
+ *    and matches the URLs client-side — see `issue-scan.ts` ▸
+ *    {@link adoptGuardWiql}, which explains why it is capped and why it is not
+ *    the statement `drift` uses. A failed guard query is reported and does not
+ *    block the adoption: this is a safety net, and one that refuses to adopt
+ *    because it could not run would be worse than the thing it prevents.
+ *
+ * `pharos issue drift` is still the sweep that finds a half-linked pair nobody
+ * retried, and reports it as `one-sided` with the same repair.
+ */
+/** The Basic process's name for a reported problem. Overridden with `--type`. */
+const DEFAULT_WORK_ITEM_TYPE = "Issue";
+export async function runIssue(io, session, positionals, options) {
+    const verb = positionals[0];
+    switch (verb) {
+        case "adopt":
+            return runAdopt(io, session, positionals.slice(1), options);
+        case "link":
+            return runLink(io, session, positionals.slice(1));
+        case "say":
+            return runSay(io, session, positionals.slice(1), options);
+        case "trail":
+            return runTrail(io, session, positionals.slice(1));
+        case "drift":
+            return runDrift(io, session, positionals.slice(1), options);
+        case "backfill":
+            return runBackfill(io, session, positionals.slice(1), options);
+        case "close":
+            return runClose(io, session, positionals.slice(1), options);
+        case undefined:
+            throw usageError("Which issue verb? adopt, link, say, trail, drift or backfill. Reading and writing an "
+                + "issue itself is `gh`.", { verbs: ISSUE_VERBS });
+        default:
+            throw usageError(`Unknown issue verb "${verb}". This owns the EDGE — ${ISSUE_VERBS.join(", ")} — and `
+                + "nothing else: listing, viewing and commenting on an issue are `gh`'s job. Closing "
+                + "one END is `gh issue close`; closing the PAIR is `pharos issue close`.", { verbs: ISSUE_VERBS });
+    }
+}
+const ISSUE_VERBS = ["adopt", "link", "say", "trail", "drift", "backfill", "close"];
+// MARK: - adopt
+/**
+ * `pharos issue adopt <repo#n>` — the issue becomes a work item, and both ends
+ * of the link are written.
+ *
+ * The `Hyperlink` relation and `--parent` go into the **same patch as the
+ * fields**, for the reason `pharos create` puts a parent there: a create
+ * followed by a relation add leaves a window where the work item exists and
+ * points at nothing, and if the second call fails the window never closes.
+ */
+async function runAdopt(io, session, positionals, options) {
+    const ref = await resolveIssue(session, positionals[0], "adopt");
+    const coordinate = { repo: ref.repo, number: ref.number };
+    const github = await session.github();
+    // Throws `PullRequestNotAnIssueError` for a PR number, which resolves through
+    // this endpoint and is out of scope for v1 (plan §13.3).
+    const issue = await github.issues.get(ref);
+    const comments = await github.issues.comments(ref);
+    const existing = linksFromComments(coordinate, comments);
+    if (existing.length > 0) {
+        return alreadyAdopted(io, session, coordinate, issue, existing);
+    }
+    // Nothing on the issue says it is adopted — which is also true of the state
+    // where a work item exists and only its comment is missing. THROWS a refusal
+    // when it finds one; a second work item is the damage this whole verb has to
+    // avoid.
+    const boardCheck = await refuseIfAlreadyTracked(session, coordinate);
+    const type = options.type ?? DEFAULT_WORK_ITEM_TYPE;
+    const title = options.title ?? issue.title;
+    const url = issueUrl(coordinate);
+    const parent = options.parent === undefined ? undefined : await resolveParent(session, options.parent);
+    const ops = adoptionOps(issue, { title, parent });
+    if (session.previewOnly) {
+        return report(io, session, {
+            applied: false,
+            dryRun: true,
+            created: false,
+            issue: { ...coordinate, title: issue.title, state: issue.state, url },
+            workItem: { type, title },
+            ...(options.parent === undefined ? {} : { parent: options.parent }),
+            wouldWrite: ["hyperlink", "comment"],
+            // A dry run runs the guard for real, because "would this refuse" is the
+            // most useful thing a preview of this verb can answer.
+            boardCheck,
+            operations: ops,
+        });
+    }
+    const adopted = await performAdoption(session, ref, { type, title, ops });
+    return report(io, session, {
+        applied: true,
+        created: true,
+        issue: {
+            ...coordinate,
+            title: issue.title,
+            state: issue.state,
+            url,
+            author: issue.author ?? null,
+        },
+        workItem: {
+            id: adopted.workItemId,
+            type,
+            title,
+            rev: adopted.rev,
+            url: adopted.workItemUrl,
+            ...(parent === undefined ? {} : { parent: parent.id, parentTitle: parent.title }),
+        },
+        wrote: ["hyperlink", "comment"],
+        commentUrl: adopted.commentUrl,
+        // Never silent about a guard that did not run: "the board says nobody has
+        // adopted this" and "the board could not be asked" are different facts, and
+        // only one of them means the duplicate check happened.
+        boardCheck,
+    });
+}
+/**
+ * **The duplicate guard.** Refuses when a work item already tracks this issue
+ * without the issue saying so, and otherwise reports what the check cost.
+ *
+ * Two sources, cheapest first, and the order is the whole design — see this
+ * file's header ▸ *What "already linked" means*. Neither subsumes the other:
+ * the journal sees a work item created seconds ago that the query index has not
+ * indexed yet, and the board sees one this machine has no memory of.
+ */
+async function refuseIfAlreadyTracked(session, coordinate) {
+    const key = halfLinkKey(session, coordinate);
+    const remembered = await session.halfLinks.find(key);
+    if (remembered !== undefined) {
+        const item = await readHalfLinked(session, coordinate, remembered.workItem);
+        if (item !== undefined) {
+            throw trackedRefusal(coordinate, {
+                workItemIds: [remembered.workItem],
+                source: "journal",
+                since: remembered.at,
+                workItem: summariseWorkItem(session, item),
+            });
+        }
+        // The work item is gone, or somebody removed its hyperlink on purpose.
+        // Either way the entry describes a state that no longer exists, and a
+        // remembered failure must never be able to block a legitimate adoption.
+        // **Not during a dry run**, which changes nothing anywhere — it costs the
+        // next preview one read and keeps that promise unqualified.
+        if (!session.previewOnly)
+            await session.halfLinks.forget(key);
+    }
+    let items;
+    try {
+        items = await session.client.wiql.queryAndFetch(adoptGuardWiql(), {
+            expand: "relations",
+            top: ADOPT_GUARD_LIMIT,
+        });
+    }
+    catch (error) {
+        // Reported, never fatal. A process template that does not expose
+        // `System.HyperLinkCount`, or a token that cannot run WIQL, would otherwise
+        // turn a safety net into a verb that no longer works — and the write it was
+        // guarding is one this caller explicitly asked for.
+        return {
+            ran: false,
+            problem: String(failureOf(error).body["message"] ?? error),
+            wiql: adoptGuardWiql(),
+            hint: "The board was NOT checked for a work item that already links this issue, so a "
+                + "half-linked pair from another machine would not have been seen. `pharos issue drift "
+                + "--repo <owner/name>` is the same question asked deliberately.",
+        };
+    }
+    const found = linksOnWorkItems(items, (item) => describeWorkItem(session, item), (item) => linksFromHyperlinks(item.id, hyperlinkUrls(item)));
+    const claims = claimsOn(found, coordinate);
+    if (claims.length > 0) {
+        throw trackedRefusal(coordinate, {
+            workItemIds: [...new Set(claims.map((claim) => claim.workItem.id))],
+            source: "board",
+            workItem: { ...claims[0].workItem },
+        });
+    }
+    return {
+        ran: true,
+        workItems: items.length,
+        // **Both numbers, and the second one is the one that catches this check
+        // going blind.** `workItems` counts what the query matched; `links` counts
+        // the GitHub issue URLs actually parsed off them. A guard narrowing on the
+        // wrong field, or reading relations it never asked to be expanded, reports
+        // work items and zero links — which is #820's failure exactly: a check that
+        // answers all-clear forever because it is looking at nothing.
+        links: found.length,
+        // A capped scan that found nothing is not the same answer as a complete one
+        // that found nothing, and printing them identically is how a partial check
+        // gets read as an all-clear.
+        truncated: items.length >= ADOPT_GUARD_LIMIT,
+    };
+}
+/**
+ * The work item a journal entry names, **if it is still half-linked to this
+ * issue**.
+ *
+ * A remembered failure is a hint, never a verdict. Three things can have
+ * happened since: it was repaired (then the marker is on the issue and this
+ * code was never reached), it was deleted, or somebody removed the hyperlink by
+ * hand. Only the first of those is worth refusing over, so this costs one read
+ * — and one read, on the path where an agent is about to create a duplicate
+ * work item, is not a cost worth arguing about.
+ */
+async function readHalfLinked(session, coordinate, workItemId) {
+    let item;
+    try {
+        item = await session.client.workItems.get(workItemId, { expand: "relations" });
+    }
+    catch {
+        // Deleted, moved to a project this token cannot see, or unreadable for a
+        // reason the create is about to hit anyway. Not evidence of a live link.
+        return undefined;
+    }
+    const links = linksFromHyperlinks(workItemId, hyperlinkUrls(item));
+    const linked = links.some((link) => link.repo === normalizeRepo(coordinate.repo) && link.issueNumber === coordinate.number);
+    return linked ? item : undefined;
+}
+/**
+ * "A work item already tracks this issue and the issue does not say so."
+ *
+ * **Exit 3 and no write**, where the marker path is exit 0. The difference is
+ * real: there the state the caller asked for already holds, and here the link
+ * is genuinely incomplete and finishing it needs a different command. So this
+ * hands over that command — the same literal string the half-link failure
+ * carried, so a caller that kept the error and a caller that retried blind end
+ * up typing the same thing.
+ */
+function trackedRefusal(coordinate, found) {
+    const label = formatIssueCoordinate(coordinate);
+    const ids = found.workItemIds;
+    const one = ids.length === 1 ? ids[0] : undefined;
+    const recover = one === undefined ? undefined : `pharos issue link ${label} ${one}`;
+    const message = one === undefined
+        ? `${label} is already tracked by ${ids.length} work items (${ids.join(", ")}), none of `
+            + "which the issue mentions. Adopting would add another — `pharos issue trail` shows what "
+            + "is there, and one of them wants unlinking before this can be resolved."
+        : `${label} is ALREADY tracked by work item #${one}, which links the issue while the issue `
+            + "says nothing about it — what a failed `adopt` leaves behind. Nothing was created: a "
+            + `second work item is not the repair. Finish the one that exists with \`${recover}\`.`;
+    return refusal(message, {
+        issue: coordinate,
+        ...(one === undefined ? {} : { workItemId: one }),
+        workItemIds: [...ids],
+        // The same three keys the half-linked failure carries, so anything that
+        // learned to read that error reads this one for free.
+        halfLinked: true,
+        created: false,
+        wrote: [],
+        evidence: ["hyperlink"],
+        ...(recover === undefined ? {} : { recover }),
+        // Which of the two guards saw it, because they answer different questions:
+        // `journal` means this machine started that adoption, `board` means
+        // somebody's did.
+        foundBy: found.source,
+        ...(found.since === undefined || found.since === "" ? {} : { since: found.since }),
+        ...(found.workItem === undefined ? {} : { workItem: found.workItem }),
+    });
+}
+/** Which issue, on which board — see `half-link.ts` for why the board is part of it. */
+function halfLinkKey(session, coordinate) {
+    return {
+        repo: normalizeRepo(coordinate.repo),
+        issue: coordinate.number,
+        organization: session.client.organization,
+        project: session.client.project ?? null,
+    };
+}
+/**
+ * A parent, read once.
+ *
+ * Resolved rather than composed from the id: `addParent` wants the parent's
+ * canonical url, and a parent that does not exist fails HERE by name instead of
+ * arriving as an opaque 400 about a relation.
+ *
+ * Separated from {@link adoptionOps} because `backfill` adopts many issues under
+ * **one** parent, and reading it once per issue would be four hundred requests
+ * for one answer that cannot change during the run.
+ */
+async function resolveParent(session, id) {
+    const parent = await session.client.workItems.get(id);
+    if (typeof parent.url !== "string" || parent.url === "") {
+        throw usageError(`Work item #${id} did not report a url, so it cannot be linked as a parent.`);
+    }
+    return { id, url: parent.url, title: titleOf(parent) };
+}
+/**
+ * The patch that turns one issue into one work item.
+ *
+ * **The `Hyperlink` relation and the parent ride in the create patch**, for the
+ * reason `pharos create` puts a parent there: a create followed by a relation
+ * add leaves a window where the work item exists and points at nothing, and if
+ * the second call fails the window never closes.
+ */
+function adoptionOps(issue, options) {
+    const coordinate = { repo: issue.repo, number: issue.number };
+    const ops = [
+        setField("System.Title", options.title),
+        ...setMarkdown("System.Description", descriptionFor(issue)),
+        // The relation's comment is what a person scanning the Links tab reads, and
+        // `contoso/widgets#45` is the one string that identifies the issue there.
+        addHyperlink(issueUrl(coordinate), formatIssueCoordinate(coordinate)),
+    ];
+    if (options.parent !== undefined)
+        ops.push(addParent(options.parent.url));
+    return ops;
+}
+/**
+ * Create the work item, then write the GitHub half. **The two writes of an
+ * adoption, in the one place both doors go through.**
+ *
+ * `adopt` and `backfill` differ in how they choose an issue and in what they
+ * print; they must not differ by a byte in what they *write*, or the bulk route
+ * would be a second adoption with its own failure modes and its own idea of what
+ * a link looks like. That is the "second implementation that drifts" failure
+ * `AGENTS.md` names three times, and it would be worse here than usual: the
+ * drifting one would be the one that runs four hundred times unattended.
+ *
+ * **The window between the two writes is written down before it opens.** From
+ * the create until the comment lands, a work item exists that neither index can
+ * find — see `half-link.ts`. Recording it here rather than in the failure
+ * handler is deliberate: a `catch` sees an HTTP error and misses ctrl-C, a
+ * killed process and a closed laptop, which leave exactly the same orphan.
+ */
+async function performAdoption(session, ref, plan) {
+    const created = await session.client.workItems.create(plan.type, plan.ops, {
+        suppressNotifications: true,
+    });
+    const workItemUrl = session.workItemUrl(created);
+    const key = halfLinkKey(session, { repo: ref.repo, number: ref.number });
+    await session.halfLinks.record({ ...key, workItem: created.id, at: new Date().toISOString() });
+    const comment = await postLinkComment(session, ref, {
+        workItemId: created.id,
+        workItemUrl,
+        workItemTitle: plan.title,
+        // The work item exists from here on. If the comment fails, the failure has
+        // to carry the id or nothing anywhere names what was just created.
+        createdWorkItem: created.id,
+    });
+    // Both halves are written, so there is no longer a window to remember. The
+    // entry that survives a failure here is the one the next `adopt` refuses on.
+    await session.halfLinks.forget(key);
+    return {
+        workItemId: created.id,
+        rev: created.rev,
+        workItemUrl,
+        commentUrl: comment.htmlUrl ?? null,
+    };
+}
+/**
+ * A second `adopt` of an issue that already carries a marker.
+ *
+ * **Exit 0 with `created: false`, not a refusal.** The state the caller asked
+ * for already holds, and an agent that retries a call it cannot tell succeeded
+ * is the normal case rather than the odd one. Creating a second work item would
+ * be the actual damage.
+ *
+ * Two states here are genuinely wrong and are refused instead:
+ *
+ *   - **Two different work items** claim the issue. Picking one would be
+ *     inventing an answer to the question this whole feature exists to answer.
+ *   - The work item the marker names **cannot be read**. It may be deleted, or
+ *     in a project this token cannot see; either way "already adopted, here it
+ *     is" would be a lie, and reporting the id with what went wrong is the only
+ *     honest answer.
+ */
+async function alreadyAdopted(io, session, coordinate, issue, links) {
+    const ids = [...new Set(links.map((link) => link.workItemId))];
+    if (ids.length > 1) {
+        throw refusal(`${formatIssueCoordinate(coordinate)} carries markers for ${ids.length} different work `
+            + `items (${ids.join(", ")}). Adopting again would add a third — resolve which one is `
+            + "right first; `pharos issue trail` shows all of them.", { issue: coordinate, workItemIds: ids });
+    }
+    const workItemId = ids[0];
+    // The marker is on the issue, so whatever this machine remembered about an
+    // unfinished adoption of it is settled. Left in place it would cost one
+    // pointless read on some future run. **Not during a dry run**: a preview
+    // changes nothing anywhere, and that includes here.
+    if (!session.previewOnly) {
+        await session.halfLinks.forget(halfLinkKey(session, coordinate));
+    }
+    let item;
+    try {
+        item = await session.client.workItems.get(workItemId, { expand: "relations" });
+    }
+    catch (error) {
+        const { kind, code, body } = failureOf(error);
+        throw new CliError(`${formatIssueCoordinate(coordinate)} is already adopted as work item #${workItemId}, and `
+            + `that work item could not be read: ${String(body["message"] ?? "")}`, kind, code, { issue: coordinate, workItemId, cause: body });
+    }
+    return report(io, session, {
+        applied: false,
+        created: false,
+        unchanged: true,
+        issue: { ...coordinate, title: issue.title, state: issue.state, url: issueUrl(coordinate) },
+        workItem: summariseWorkItem(session, item),
+        evidence: mergeLinks(links)[0]?.evidence ?? [],
+        message: `${formatIssueCoordinate(coordinate)} is already adopted as #${workItemId}. Nothing was `
+            + "created.",
+    });
+}
+/** The issue's own words, under a line saying where they came from. */
+function descriptionFor(issue) {
+    const coordinate = formatIssueCoordinate({ repo: issue.repo, number: issue.number });
+    const reporter = issue.author === undefined ? "" : ` — reported by \`@${issue.author}\``;
+    const header = `Adopted from [${coordinate}](${issue.htmlUrl})${reporter}.`;
+    const body = issue.body?.trim();
+    // The body crosses because the trail is the point: "the link exists and
+    // carries nothing" is the complaint against the Azure Boards app (plan §1),
+    // and a work item whose description says only "see GitHub" repeats it.
+    return body === undefined || body === "" ? header : `${header}\n\n---\n\n${body}`;
+}
+// MARK: - link
+/**
+ * `pharos issue link <repo#n> <id>` — join an existing pair, or finish a join
+ * that half-happened.
+ *
+ * Both halves are checked before either is written, and only the missing ones
+ * are written, so running it twice is a no-op and running it after a failed
+ * `adopt` completes the link rather than duplicating the half that survived.
+ */
+async function runLink(io, session, positionals) {
+    const ref = await resolveIssue(session, positionals[0], "link");
+    const coordinate = { repo: ref.repo, number: ref.number };
+    const workItemId = workItemArgument(positionals[1], "Which work item? `pharos issue link owner/name#45 4821`.");
+    const github = await session.github();
+    const issue = await github.issues.get(ref);
+    const comments = await github.issues.comments(ref);
+    const item = await session.client.workItems.get(workItemId, { expand: "relations" });
+    const url = issueUrl(coordinate);
+    const fromComments = linksFromComments(coordinate, comments);
+    const fromRelations = linksFromHyperlinks(workItemId, hyperlinkUrls(item));
+    // **An issue may belong to one work item; a work item may reference many
+    // issues.** The asymmetry is not fussiness: "which work item tracks this
+    // issue" is the question the trail answers, and two answers is no answer. The
+    // other direction has an obvious meaning — one work item, several reported
+    // symptoms — so it is allowed.
+    const claimedBy = [...new Set(fromComments.map((link) => link.workItemId))].filter((id) => id !== workItemId);
+    if (claimedBy.length > 0) {
+        throw refusal(`${formatIssueCoordinate(coordinate)} is already linked to work item `
+            + `${claimedBy.map((id) => `#${id}`).join(", ")}. An issue belongs to ONE work item — `
+            + "unlink the other end first, or check `pharos issue trail` for what is already there.", { issue: coordinate, workItemId, linkedTo: claimedBy });
+    }
+    const hasHyperlink = fromRelations.some((link) => link.repo === normalizeRepo(coordinate.repo) && link.issueNumber === coordinate.number);
+    const hasComment = fromComments.some((link) => link.workItemId === workItemId);
+    if (hasHyperlink && hasComment) {
+        return report(io, session, {
+            applied: false,
+            unchanged: true,
+            issue: { ...coordinate, title: issue.title, state: issue.state, url },
+            workItem: summariseWorkItem(session, item),
+            // Found by the pair rather than taken as the first row: a work item is
+            // allowed to reference several issues, so `[0]` would be an assumption
+            // about ordering that happens to hold.
+            evidence: mergeLinks(fromComments, fromRelations).find((link) => link.repo === normalizeRepo(coordinate.repo)
+                && link.issueNumber === coordinate.number
+                && link.workItemId === workItemId)?.evidence ?? [],
+            message: `${formatIssueCoordinate(coordinate)} and #${workItemId} are already linked.`,
+        });
+    }
+    const missing = [
+        ...(hasHyperlink ? [] : ["hyperlink"]),
+        ...(hasComment ? [] : ["comment"]),
+    ];
+    if (session.previewOnly) {
+        return report(io, session, {
+            applied: false,
+            dryRun: true,
+            issue: { ...coordinate, title: issue.title, state: issue.state, url },
+            workItem: summariseWorkItem(session, item),
+            wouldWrite: missing,
+        });
+    }
+    if (!hasHyperlink) {
+        // Guarded on the rev of the read the relations came from, like every other
+        // relation write here: adding a relation is itself a revision, so a
+        // teammate's write lands as a conflict rather than on top of.
+        await session.client.workItems.updateWithRev(workItemId, item.rev, [addHyperlink(url, formatIssueCoordinate(coordinate))], { suppressNotifications: true });
+    }
+    let commentUrl = null;
+    if (!hasComment) {
+        const comment = await postLinkComment(session, ref, {
+            workItemId,
+            workItemUrl: session.workItemUrl(item),
+            workItemTitle: titleOf(item) ?? undefined,
+        });
+        commentUrl = comment.htmlUrl ?? null;
+        // This is the repair for a half-linked adoption, and it just completed one.
+        // Nothing depends on the entry going — the marker now answers the question
+        // by itself — but leaving it would keep a resolved failure on the books.
+        await session.halfLinks.forget(halfLinkKey(session, coordinate));
+    }
+    return report(io, session, {
+        applied: true,
+        issue: { ...coordinate, title: issue.title, state: issue.state, url },
+        workItem: summariseWorkItem(session, item),
+        wrote: missing,
+        commentUrl,
+    });
+}
+// MARK: - say
+/**
+ * How much of the message reaches the board when nobody wrote a `--summary`.
+ *
+ * Truncating is safe **only because the comment's URL always travels with it**.
+ * The board never carries the last word — it carries enough to know whether to
+ * click, and the click lands on the exact comment rather than on the issue.
+ */
+const SUMMARY_LIMIT = 200;
+/**
+ * `pharos issue say <owner/name#45> <message>` — one event, two audiences, and
+ * the asymmetry is the whole verb.
+ *
+ * | | GitHub | Azure DevOps |
+ * |---|---|---|
+ * | who reads it | the reporter, who does **not** have an Azure DevOps account and never will | the team |
+ * | what they get | the full explanation, in their register | a summary, and the URL of the comment that carries the rest |
+ *
+ * Writing the same words to both would be `gh issue comment` followed by
+ * `pharos comment add`, and that is *not* what this is: those two are equally
+ * long in both places and neither knows the other happened. Plan §8.
+ *
+ * ## The loop guard, which is the reason this verb is dangerous
+ *
+ * Get it wrong and Pharos summarises its own summary back across the bridge,
+ * forever. It has two halves and only one of them is on this path:
+ *
+ * 1. **Every comment posted here carries the `pharos:v1` trailer**, because
+ *    that is what the read side keys on. `isPharosAuthored` is total only if
+ *    nothing anywhere posts an unmarked Pharos comment — a single one is a
+ *    comment the sweep reads as a human's, and the loop that starts from it
+ *    does not stop. The trailer is composed by `gh-core`, never here.
+ * 2. **A message that already carries a trailer is refused.** That is somebody
+ *    handing Pharos its own output back — a mirrored body, a copy-paste, a
+ *    script re-posting what it read — and it is the loop starting one step
+ *    before any sweep could see it. The app's queue refuses exactly this
+ *    (#785); both doors refuse the same thing.
+ *
+ * **The guard keys on content, never on `sender.login`.** GitHub events carry
+ * an actor and Azure DevOps events do not, which makes the actor look like the
+ * easy answer here and is the trap: every client writes with its own `gh`
+ * credential, so `sender.login == me` is *also* true of the human typing into
+ * the web UI. Suppressing on it silently swallows their real comments (§5).
+ *
+ * ## GitHub first, and that is not the order `adopt` uses
+ *
+ * `adopt` and `link` write Azure DevOps first because the work item id does not
+ * exist until the create lands. Here the dependency points the other way: the
+ * board's comment carries the GitHub comment's URL, which does not exist until
+ * the POST returns. So the half-written state is the mirror image — GitHub
+ * written, the board not — and it gets the same treatment: reported with the
+ * URL and a runnable command, never swallowed.
+ *
+ * The work item is **read before anything is posted**, because the GitHub half
+ * is published on somebody else's repository and cannot be taken back. A
+ * message announcing a work item that turns out to be unreadable is worse than
+ * a failed command.
+ *
+ * **Re-running is not the recovery, and that is the one thing to know.** A
+ * comment is an append: `say` twice says it twice. So the error left by a
+ * half-written fan-out names `pharos comment add` — finish the missing half —
+ * rather than inviting a retry that would post a second public comment.
+ */
+async function runSay(io, session, positionals, options) {
+    const target = positionals[0];
+    if (target !== undefined && /^\d+$/.test(target.trim())) {
+        // A work item may hyperlink SEVERAL issues, so that end names no single
+        // audience — which is why this verb has one direction while `trail` has two.
+        throw usageError(`\`say\` starts from the issue, not from work item #${target.trim()} — a work item can `
+            + "reference several issues and there would be no one reporter to answer. "
+            + `\`pharos issue trail ${target.trim()}\` names them.`, { given: target.trim() });
+    }
+    const ref = await resolveIssue(session, target, "say");
+    const coordinate = { repo: ref.repo, number: ref.number };
+    const message = messageArgument(positionals[1], options.message);
+    // Before any call. The refusal is about what was HANDED to this command, so
+    // spending a request to discover it would only make it slower.
+    if (isPharosAuthored(message)) {
+        throw refusal("That message already carries a pharos:v1 trailer, which means it is a comment Pharos "
+            + "wrote. Posting it again is how the fan-out starts summarising its own summaries — "
+            + "say what you mean in your own words instead.", { issue: coordinate, hint: "The trailer is added on the way out; never pass one in." });
+    }
+    const github = await session.github();
+    const issue = await github.issues.get(ref);
+    const comments = await github.issues.comments(ref);
+    const links = linksFromComments(coordinate, comments);
+    const workItemId = soleWorkItem(coordinate, links);
+    // Read first: past the POST below the message is public on a repository that
+    // may not be ours, and "the work item it names cannot be read" is a fact
+    // worth having BEFORE that rather than after.
+    let item;
+    try {
+        item = await session.client.workItems.get(workItemId);
+    }
+    catch (error) {
+        const { kind, code, body } = failureOf(error);
+        throw new CliError(`${formatIssueCoordinate(coordinate)} is linked to work item #${workItemId}, and that work `
+            + `item could not be read: ${String(body["message"] ?? "")}. Nothing was posted.`, kind, code, { issue: coordinate, workItemId, wrote: [], cause: body });
+    }
+    const url = issueUrl(coordinate);
+    const workItemUrl = session.workItemUrl(item);
+    // Composed by `gh-core`, so this and the macOS app produce the same bytes and
+    // the shared fixture means something. The trailer arrives with it.
+    const githubBody = composeLinkComment({
+        repo: ref.repo,
+        issue: ref.number,
+        adoId: workItemId,
+        workItemUrl,
+        workItemTitle: titleOf(item) ?? undefined,
+        message,
+    });
+    const summary = summaryFor(message, options.summary);
+    if (session.previewOnly) {
+        return report(io, session, {
+            applied: false,
+            dryRun: true,
+            issue: { ...coordinate, title: issue.title, state: issue.state, url },
+            workItem: summariseWorkItem(session, item),
+            wouldWrite: ["github-comment", "ado-comment"],
+            // Both bodies, in full. A preview of a two-audience write that showed one
+            // audience's words would hide the half this verb exists to get right.
+            //
+            // The board's half links the ISSUE here rather than the comment, and that
+            // is the one thing a preview cannot be honest about: the comment does not
+            // exist until it is posted, so there is no anchor to show.
+            github: { body: githubBody },
+            ado: { body: adoSummaryComment({ coordinate, link: url, summary }) },
+            summary: { ...summary },
+        });
+    }
+    let posted;
+    try {
+        posted = await github.issues.comment(ref, githubBody);
+    }
+    catch (error) {
+        const { kind, code, body } = failureOf(error);
+        throw new CliError(`Nothing was posted: GitHub refused the comment on ${formatIssueCoordinate(coordinate)}: `
+            + String(body["message"] ?? ""), kind, code, {
+            platform: "github",
+            issue: coordinate,
+            workItemId,
+            // Named even though it is empty: "which half landed" is the first thing
+            // a caller needs from a two-platform verb, and absent is not the same
+            // answer as none.
+            wrote: [],
+            hint: "Neither platform was written, so re-running this command is safe.",
+            cause: body,
+        });
+    }
+    // Past this line the comment is public on somebody else's repository.
+    const commentUrl = posted.htmlUrl ?? url;
+    const adoBody = adoSummaryComment({ coordinate, link: commentUrl, summary });
+    let adoComment;
+    try {
+        adoComment = await session.client.comments.add(workItemId, adoBody);
+    }
+    catch (error) {
+        const { kind, code, body } = failureOf(error);
+        const recover = `pharos comment add ${workItemId} --stdin`;
+        throw new CliError(`The GitHub comment on ${formatIssueCoordinate(coordinate)} was POSTED and the Azure DevOps `
+            + `summary on #${workItemId} was not: ${String(body["message"] ?? "")}`, kind, code, {
+            platform: "azure-devops",
+            issue: coordinate,
+            workItemId,
+            wrote: ["github-comment"],
+            halfSaid: true,
+            github: { commentId: posted.id, commentUrl },
+            // The exact text, so finishing the job needs no reconstruction — and so
+            // the URL inside it is the one already published rather than a new one.
+            adoComment: adoBody,
+            recover,
+            hint: "Do NOT re-run `pharos issue say` — a comment is an append, so it would post a SECOND "
+                + `public comment on ${formatIssueCoordinate(coordinate)}. Pipe the text in `
+                + `\`adoComment\` into \`${recover}\` to write the half that is missing.`,
+            cause: body,
+        });
+    }
+    return report(io, session, {
+        applied: true,
+        issue: {
+            ...coordinate,
+            title: issue.title,
+            state: issue.state,
+            url,
+            author: issue.author ?? null,
+        },
+        workItem: summariseWorkItem(session, item),
+        wrote: ["github-comment", "ado-comment"],
+        github: { commentId: posted.id, commentUrl },
+        ado: { commentId: adoComment.id },
+        summary: { ...summary },
+    });
+}
+/**
+ * The one work item this issue belongs to, or a refusal saying why there isn't
+ * one.
+ *
+ * Both refusals matter and they are different states. **Nothing** means the
+ * issue was never adopted, and `say` will not invent the other end of a link —
+ * `adopt` is the verb that creates one. **Several** is the state `adopt` and
+ * `link` already refuse: an issue belongs to one work item, so two answers is
+ * no answer, and here it would also mean choosing whose board hears about it.
+ */
+function soleWorkItem(coordinate, links) {
+    const ids = [...new Set(links.map((link) => link.workItemId))];
+    if (ids.length === 0) {
+        const label = formatIssueCoordinate(coordinate);
+        throw refusal(`${label} is not linked to any work item, so there is no board to summarise this on. `
+            + `Adopt it first: \`pharos issue adopt ${label}\`, or \`pharos issue link ${label} <id>\` `
+            + "if the work item already exists.", {
+            issue: coordinate,
+            recover: `pharos issue adopt ${label}`,
+            // Said explicitly: `say` is a fan-out, not a comment verb wearing a
+            // link. Somebody who only wants to talk to GitHub already has `gh`.
+            hint: "`say` writes to both platforms — commenting on GitHub alone is `gh issue comment`.",
+        });
+    }
+    if (ids.length > 1) {
+        throw refusal(`${formatIssueCoordinate(coordinate)} carries markers for ${ids.length} different work `
+            + `items (${ids.join(", ")}), so there is no one board to summarise this on. `
+            + "`pharos issue trail` shows all of them; resolve which one is right first.", { issue: coordinate, workItemIds: ids });
+    }
+    return ids[0];
+}
+/**
+ * What the board hears.
+ *
+ * `--summary` when there is one. Otherwise the first paragraph, collapsed to a
+ * line and cut at {@link SUMMARY_LIMIT} on a word boundary — which is a guess,
+ * and is allowed to be one **only because the comment's URL goes with it**. The
+ * board is never the record of what was said; GitHub is, and the summary's job
+ * is to be enough to decide whether to click.
+ *
+ * `complete` is tracked rather than assumed so the composed comment can stop
+ * claiming there is more to read when there isn't. A `--summary` is never
+ * called complete: only its author knows whether it left anything out, and
+ * over-claiming is the failure that matters.
+ */
+function summaryFor(message, given) {
+    const written = given?.trim();
+    if (written !== undefined && written !== "") {
+        return { text: written, source: "given", complete: false };
+    }
+    const whole = collapse(message);
+    // `\r` is in the class on purpose: `--file` reads whatever is on disk, and a
+    // CRLF file would otherwise have no paragraph breaks at all — every message
+    // one paragraph, every summary a truncation.
+    const paragraph = collapse(message.trim().split(/\n[ \t\r]*\n/)[0] ?? "");
+    if (paragraph.length <= SUMMARY_LIMIT) {
+        return { text: paragraph, source: "derived", complete: paragraph === whole };
+    }
+    const cut = paragraph.slice(0, SUMMARY_LIMIT);
+    const space = cut.lastIndexOf(" ");
+    // Only break on a word if the word boundary is near the end; a single long
+    // token would otherwise cut the summary down to almost nothing.
+    const kept = space > SUMMARY_LIMIT * 0.6 ? cut.slice(0, space) : cut;
+    return { text: `${kept.trimEnd()}…`, source: "derived", complete: false };
+}
+/** Every run of whitespace to one space. A board comment is one paragraph. */
+function collapse(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/**
+ * The board's half: the summary, then where the rest of it is.
+ *
+ * The link is to the **comment**, not to the issue — a reader who has to find
+ * the right comment among forty has been handed a search, not a link. It falls
+ * back to the issue only when GitHub returned no `html_url`.
+ *
+ * There is deliberately **no marker on this side.** The Azure DevOps echo guard
+ * is the hub's `rev <= knownRev` (§5) and needs no help from the body; a
+ * trailer here would be a second, unread mechanism, and the one nobody reads is
+ * the one that rots.
+ */
+function adoSummaryComment(options) {
+    const label = formatIssueCoordinate(options.coordinate);
+    const where = options.summary.complete
+        ? `Posted to [${label}](${options.link}).`
+        : `Posted to [${label}](${options.link}) — the full text is there.`;
+    return `${options.summary.text}\n\n${where}`;
+}
+function messageArgument(positional, provided) {
+    const text = positional ?? provided;
+    if (text === undefined || text.trim() === "") {
+        throw usageError("No message. Pass it as an argument, or use --text/--file/--stdin — an explanation written "
+            + "for the reporter is usually longer than a command line wants.");
+    }
+    return text;
+}
+// MARK: - trail
+/**
+ * `pharos issue trail <id|repo#n>` — the whole trail, from either end.
+ *
+ * **The output shape does not depend on which end you started from.** `from`
+ * says which was the anchor and every row still carries both sides, so nothing
+ * consuming this has to branch on the argument it passed. Read-only, and it
+ * spends no write budget — `--max-writes 0` is a perfectly good way to run it.
+ *
+ * `evidence` is the useful field. `["hyperlink","marker"]` is a complete link;
+ * one of them alone is a link that half-exists, which is the state `adopt`
+ * leaves behind when the second write fails and the state `link` repairs.
+ */
+async function runTrail(io, session, positionals) {
+    const target = positionals[0];
+    if (target === undefined || target === "") {
+        throw usageError("From which end? `pharos issue trail 4821` or `pharos issue trail owner/name#45`.");
+    }
+    return /^\d+$/.test(target.trim())
+        ? trailFromWorkItem(io, session, Number(target.trim()))
+        : trailFromIssue(io, session, target);
+}
+async function trailFromWorkItem(io, session, id) {
+    const item = await session.client.workItems.get(id, { expand: "relations" });
+    const anchor = summariseWorkItem(session, item);
+    const hyperlinks = linksFromHyperlinks(id, hyperlinkUrls(item));
+    const rows = await Promise.all(hyperlinks.map(async (link) => {
+        const coordinate = { repo: link.repo, number: link.issueNumber };
+        const side = await readIssueSide(session, coordinate);
+        if (side.problem !== undefined) {
+            return {
+                workItem: anchor,
+                issue: null,
+                evidence: link.evidence,
+                twoSided: false,
+                problem: side.problem,
+            };
+        }
+        const merged = mergeLinks([link], side.links.filter((found) => found.workItemId === id))[0];
+        return {
+            workItem: anchor,
+            issue: summariseIssue(side.issue, coordinate),
+            evidence: merged?.evidence ?? link.evidence,
+            twoSided: merged !== undefined && isTwoSided(merged),
+            problem: null,
+        };
+    }));
+    return report(io, session, {
+        from: "workItem",
+        workItem: anchor,
+        issue: null,
+        links: rows,
+    });
+}
+async function trailFromIssue(io, session, text) {
+    const ref = await resolveIssue(session, text, "trail");
+    const coordinate = { repo: ref.repo, number: ref.number };
+    const github = await session.github();
+    const issue = await github.issues.get(ref);
+    const comments = await github.issues.comments(ref);
+    const fromComments = linksFromComments(coordinate, comments);
+    const anchor = summariseIssue(issue, coordinate);
+    const rows = await Promise.all(fromComments.map(async (link) => {
+        let item;
+        try {
+            item = await session.client.workItems.get(link.workItemId, { expand: "relations" });
+        }
+        catch (error) {
+            // A marker naming a work item that cannot be read is a real state — the
+            // item was deleted, or it is in a project this token cannot see — and
+            // reporting it as a failed command would hide the half of the trail
+            // that WAS readable.
+            return {
+                // The same keys as a readable one, with the unknown ones null. A row
+                // that changes SHAPE when something goes wrong makes the failure case
+                // the one a consumer has not written code for.
+                workItem: {
+                    id: link.workItemId,
+                    type: null,
+                    title: null,
+                    state: null,
+                    assignedTo: null,
+                    url: session.workItemUrl({ id: link.workItemId }),
+                },
+                issue: anchor,
+                evidence: link.evidence,
+                twoSided: false,
+                problem: failureOf(error).body["message"] ?? "the work item could not be read",
+            };
+        }
+        const merged = mergeLinks([link], linksFromHyperlinks(link.workItemId, hyperlinkUrls(item)).filter((found) => found.issueNumber === coordinate.number))[0];
+        return {
+            workItem: summariseWorkItem(session, item),
+            issue: anchor,
+            evidence: merged?.evidence ?? link.evidence,
+            twoSided: merged !== undefined && isTwoSided(merged),
+            problem: null,
+        };
+    }));
+    return report(io, session, {
+        from: "issue",
+        workItem: null,
+        issue: anchor,
+        links: rows,
+    });
+}
+/**
+ * Read the GitHub half of a link, reporting an unreachable repository rather
+ * than failing the whole command.
+ *
+ * A work item can hyperlink an issue in a repository this machine has no binding
+ * for — somebody else adopted it, on a machine configured differently. That is
+ * information, not a fault: the Azure DevOps end was read successfully and
+ * saying so with the reason the other end is missing beats an exit code that
+ * throws away what was found.
+ */
+async function readIssueSide(session, coordinate) {
+    try {
+        const github = await session.github();
+        const binding = github.binding(coordinate.repo);
+        const ref = { ...binding, number: coordinate.number };
+        const issue = await github.issues.get(ref);
+        const comments = await github.issues.comments(ref);
+        return { issue, links: linksFromComments(coordinate, comments) };
+    }
+    catch (error) {
+        return { links: [], problem: String(failureOf(error).body["message"] ?? error) };
+    }
+}
+// MARK: - drift
+/**
+ * `pharos issue drift` — the report that proves the bridge is honest, and the
+ * one thing here no other tool can produce.
+ *
+ * `gh` can list issues. Azure DevOps can list work items. Neither can say *these
+ * two disagree*, because neither holds both sides — and a link nobody checks
+ * decays quietly: an issue gets closed on GitHub and the board still shows the
+ * work in progress; a work item is marked done and the reporter, who has no
+ * Azure DevOps account and never will, is still waiting.
+ *
+ * ## What it scans, and why that is the Azure DevOps side
+ *
+ * Links, not issues. **A repository's unadopted issues are not drift** — on a
+ * repo with four hundred of them, counting "not linked" as a problem would bury
+ * the three real findings under three hundred and eighty-eight rows of noise.
+ * What is missing from the bridge is `backfill`'s question; what is *wrong*
+ * inside it is this one.
+ *
+ * So the scan starts from the board, because that is the enumerable side: a work
+ * item carries its `Hyperlink` relations on its own row, so one WIQL and one
+ * `workitemsbatch` return every link at once. GitHub cannot answer the
+ * equivalent question at all — the marker lives in a comment, so asking costs a
+ * request per issue. See `issue-scan.ts`.
+ *
+ * ## Four kinds, because they want four different actions
+ *
+ * | kind | what it means |
+ * |---|---|
+ * | `state` | both ends exist and disagree about whether the work is finished |
+ * | `missing-issue` | the work item names an issue GitHub does not have |
+ * | `one-sided` | the board has the link and the issue does not — what a failed `adopt` leaves |
+ * | `unreadable` | the GitHub end could not be read, so nothing about this pair is known |
+ *
+ * The last one is **information, not a fault, and it never fails the command**
+ * (#782). A work item can hyperlink an issue in a repository this machine has no
+ * binding for, because somebody else adopted it on a machine configured
+ * differently. Throwing that away along with everything the scan *did* learn
+ * would be the wrong trade.
+ *
+ * ## "Still open" is read from the project, never guessed
+ *
+ * A process template can rename every state, so `Closed` and `Done` are this
+ * organisation's answer rather than Azure DevOps'. The catalogue is read and the
+ * report says which source it used — and when it cannot be read the stock names
+ * are used with that stated, because a row is uninterpretable without knowing
+ * what was counted as finished. Same argument `pharos query` makes for filtering.
+ */
+async function runDrift(io, session, positionals, options) {
+    if (positionals.length > 0) {
+        throw usageError(`\`drift\` takes no argument — it scans the whole board. Did you mean \`--repo `
+            + `${positionals[0]}\` to narrow it to one repository, or \`pharos issue trail `
+            + `${positionals[0]}\` for one pair?`, { given: positionals[0] });
+    }
+    // Not fatal. A token without the work-item-type read still scans fine; it just
+    // cannot be told what "finished" means here, and saying so and using the stock
+    // names beats refusing to answer at all.
+    let catalog;
+    let catalogFailure;
+    try {
+        catalog = await session.client.workItemTypes.states();
+    }
+    catch (error) {
+        catalogFailure = error instanceof Error ? error.message : String(error);
+    }
+    const states = finishedStates(catalog, catalogFailure);
+    const statement = options.wiql ?? driftWiql();
+    let items;
+    try {
+        items = await session.client.wiql.queryAndFetch(statement, { expand: "relations" });
+    }
+    catch (error) {
+        throw explainScanFailure(error, statement, options.wiql !== undefined);
+    }
+    const found = linksOnWorkItems(items, (item) => describeWorkItem(session, item), (item) => linksFromHyperlinks(item.id, hyperlinkUrls(item)));
+    // Compared on the KEY, never with `===`. GitHub resolves a repository
+    // case-insensitively and echoes back the spelling it was created with, so
+    // `Contoso/Widgets` and `contoso/widgets` are one repository written two ways
+    // — and #787 reported a perfectly good link as half-written over exactly this.
+    const wanted = options.repo === undefined ? undefined : normalizeRepo(options.repo);
+    const selected = wanted === undefined ? found : found.filter((link) => link.repo === wanted);
+    const limit = options.limit;
+    const truncated = limit !== undefined && selected.length > limit;
+    const links = truncated ? selected.slice(0, limit) : selected;
+    const sides = await readIssueSides(session, links);
+    const drift = [];
+    let healthy = 0;
+    for (const [index, link] of links.entries()) {
+        const verdict = judgeLink(link, sides[index], states);
+        if (verdict.drift === undefined)
+            healthy += 1;
+        else
+            drift.push(verdict.drift);
+    }
+    return report(io, session, {
+        scanned: {
+            workItems: items.length,
+            links: selected.length,
+            examined: links.length,
+            repos: reposOf(links),
+            // Reported so a surprising answer is one line to diagnose rather than a
+            // mystery — and so a hand-written `--wiql` is on the record beside what it
+            // found.
+            wiql: statement,
+            // Never silent. `truncated` is the difference between "the board is clean"
+            // and "the first twenty were clean", and only one of those is worth acting
+            // on.
+            truncated,
+        },
+        finishedStates: {
+            source: states.source,
+            terminal: states.terminal,
+            ambiguous: states.ambiguous,
+            note: states.note,
+        },
+        healthy,
+        counts: tallyDrift(drift),
+        drift,
+    });
+}
+/**
+ * Read the GitHub half of every link, one repository at a time.
+ *
+ * **The repository is swept once rather than each issue fetched.** For a board
+ * with four hundred links into one repository that is four requests instead of
+ * four hundred, and it buys something a per-issue `GET` cannot: absence from a
+ * full enumeration is *evidence* that an issue is not there, where a 404 is
+ * equally consistent with a private repository, a rename, or a token that lost a
+ * scope. `missing-issue` is a claim worth being sure about — it is the kind that
+ * tells somebody a link they wrote is pointing at nothing.
+ *
+ * The marker read stays per issue, because that is where the marker is. It is
+ * the expensive half and it is bounded: {@link READ_CONCURRENCY} at a time,
+ * because GitHub's secondary rate limit is about concurrency rather than volume
+ * and tripping it bans a token somebody else is also using.
+ */
+async function readIssueSides(session, links) {
+    const sides = new Map();
+    const key = (link) => `${link.repo}#${link.issueNumber}`;
+    const byRepo = new Map();
+    for (const link of links) {
+        const existing = byRepo.get(link.repo);
+        if (existing === undefined)
+            byRepo.set(link.repo, [link]);
+        else
+            existing.push(link);
+    }
+    for (const [, group] of byRepo) {
+        const first = group[0];
+        let binding;
+        let sweep;
+        try {
+            const github = await session.github();
+            // Throws a `GitHubConfigError` naming the repo and the file when it is
+            // unbound. There is deliberately no fallback to whichever `gh` account is
+            // active (plan §2).
+            binding = github.binding(first.spelling);
+            sweep = await github.issues.list(binding, { state: "all" });
+        }
+        catch (error) {
+            // One unreadable repository must not kill the sweep — the rest of the
+            // board was read successfully and saying so with the reason beats an exit
+            // code that throws away what was found (#782).
+            const problem = String(failureOf(error).body["message"] ?? error);
+            for (const link of group)
+                sides.set(key(link), { problem });
+            continue;
+        }
+        const swept = new Map(sweep.issues.map((issue) => [issue.number, issue]));
+        await inBatches(group, READ_CONCURRENCY, async (link) => {
+            const ref = { ...binding, number: link.issueNumber };
+            const issue = swept.get(link.issueNumber);
+            if (issue === undefined) {
+                sides.set(key(link), await explainAbsence(session, ref));
+                return;
+            }
+            try {
+                const comments = await session.github().then((github) => github.issues.comments(ref));
+                sides.set(key(link), {
+                    issue: factsOf(issue),
+                    markers: linksFromComments({ repo: link.spelling, number: link.issueNumber }, comments),
+                });
+            }
+            catch (error) {
+                // The state is known and the marker is not. `markers` stays ABSENT
+                // rather than empty, because empty would mean "read, and there is no
+                // marker" — which is a half-written link, and reporting one on the
+                // strength of a failed request would be inventing a finding.
+                sides.set(key(link), {
+                    issue: factsOf(issue),
+                    problem: String(failureOf(error).body["message"] ?? error),
+                });
+            }
+        });
+    }
+    return links.map((link) => sides.get(key(link)) ?? { problem: "not read" });
+}
+/**
+ * An issue number the repository's own enumeration does not contain.
+ *
+ * One request, and only for the numbers that are already anomalous, to tell the
+ * three apart: a deleted or transferred issue (404), a **pull request** — which
+ * `/issues/{n}` resolves and which is out of scope for v1, so it is a link
+ * pointing somewhere this tool will not follow rather than a link pointing
+ * nowhere — and anything else.
+ */
+async function explainAbsence(session, ref) {
+    try {
+        const github = await session.github();
+        const issue = await github.issues.get(ref);
+        // It answered after all: the sweep and the single read disagree, which
+        // happens when an issue is created or transferred mid-sweep. Take the read.
+        return { issue: factsOf(issue) };
+    }
+    catch (error) {
+        if (error instanceof PullRequestNotAnIssueError) {
+            return {
+                problem: `${formatIssueCoordinate({ repo: ref.repo, number: ref.number })} is a pull request, not `
+                    + "an issue. Pull requests are out of scope for v1 (plan §13.3), so this link is not "
+                    + "checked either way.",
+            };
+        }
+        if (error instanceof GitHubNotFoundError) {
+            return {
+                missing: true,
+                problem: String(failureOf(error).body["message"] ?? error),
+            };
+        }
+        return { problem: String(failureOf(error).body["message"] ?? error) };
+    }
+}
+/**
+ * A failed scan, with the clause that is most likely to blame named.
+ *
+ * `System.ExternalLinkCount` is queryable on every process template Azure DevOps
+ * ships and this has not been run against a customised one, so if a project does
+ * not expose it the statement fails to parse and the message is about a query
+ * the caller never wrote. Handing over `--wiql` in the same breath turns "drift
+ * is broken" into one flag — the same escape hatch `pharos query` already has,
+ * for the same reason.
+ */
+function explainScanFailure(error, statement, handWritten) {
+    const { kind, code, body } = failureOf(error);
+    const message = String(body["message"] ?? "");
+    if (handWritten || !looksLikeWiqlRejection(message))
+        return error;
+    return new CliError(`The drift scan's query was refused: ${message}`, kind, code, {
+        wiql: statement,
+        hint: "This narrows to work items carrying an external link with [System.ExternalLinkCount] > 0. "
+            + "If this project's process does not expose that field, pass your own statement with "
+            + "--wiql — it needs to SELECT [System.Id] and should return every work item that might "
+            + "carry a GitHub hyperlink.",
+        cause: body,
+    });
+}
+/** The `IssueFacts` a drift row needs, off a `GitHubIssue`. */
+function factsOf(issue) {
+    return {
+        repo: issue.repo,
+        number: issue.number,
+        title: issue.title,
+        state: issue.state,
+        stateReason: issue.stateReason ?? null,
+        updatedAt: issue.updatedAt,
+        url: issue.htmlUrl === "" ? issueUrl({ repo: issue.repo, number: issue.number }) : issue.htmlUrl,
+    };
+}
+function describeWorkItem(session, item) {
+    const fields = item.fields ?? {};
+    const text = (name) => {
+        const value = fields[name];
+        return typeof value === "string" && value !== "" ? value : null;
+    };
+    return {
+        id: item.id,
+        type: text("System.WorkItemType"),
+        title: text("System.Title"),
+        state: text("System.State"),
+        url: session.workItemUrl(item),
+    };
+}
+// MARK: - backfill
+/**
+ * `pharos issue backfill <owner/name>` — bulk `adopt`, for the repository
+ * everybody actually has.
+ *
+ * Without this the bridge only works on a greenfield repository, which is not
+ * where anybody is. A team with four hundred open issues cannot adopt them one
+ * command at a time, and a feature they cannot start using is a feature they do
+ * not have.
+ *
+ * ## Why this is a verb and not `adopt --all`
+ *
+ * `adopt` has a contract worth keeping intact: one issue, idempotent, exit 0,
+ * and every failure is about that one issue. Bulk changes every one of those —
+ * partial success becomes the normal outcome, and "what happened" stops being a
+ * single answer. Overloading the argument to be sometimes-a-coordinate and
+ * sometimes-absent would make the safe verb's shape depend on a flag.
+ *
+ * What it must **not** be is a second adoption. Both verbs go through
+ * {@link performAdoption}, so the bytes written are the same from either door.
+ *
+ * ## Deciding what is already adopted, without four hundred requests
+ *
+ * The board is read first — one WIQL, one `workitemsbatch` — and every issue
+ * number already reached by a `Hyperlink` is subtracted from the sweep. That is
+ * correct because `adopt` writes the Azure DevOps end **first**: the half-state
+ * it can leave is a hyperlink with no comment, never the reverse.
+ *
+ * The reverse is still possible if somebody deletes a relation by hand, so the
+ * marker is re-read per issue **at adoption time** — on the handful being
+ * written, not on all four hundred. An issue that turns out to carry a marker
+ * already is skipped rather than adopted twice.
+ *
+ * ## It is resumable, and it needs no state file to be
+ *
+ * The link *is* the progress record. A second run reads the board again, finds
+ * the ones the first run adopted already linked, and carries on — so a run that
+ * stops at the write budget, at a rate limit, or because somebody pressed
+ * ctrl-C, is resumed by running the identical command again. Candidates are
+ * ordered by issue number ascending so that is true in the obvious way as well
+ * as the technical one.
+ *
+ * ## The write budget is the throttle, on purpose
+ *
+ * Four hundred adoptions is eight hundred writes against a default cap of
+ * {@link DEFAULT_WRITE_BUDGET}. Rather than discovering that halfway through,
+ * the cost is computed up front and a run that cannot finish is **refused before
+ * it starts** — naming both ways forward. Stopping halfway is recoverable here,
+ * but "it did some of it" is the outcome a caller is least able to reason about,
+ * and making somebody type the number is the point of the cap rather than a
+ * side effect of it.
+ */
+async function runBackfill(io, session, positionals, options) {
+    const repo = positionals[0];
+    if (repo === undefined || repo === "") {
+        throw usageError("Which repository? `pharos issue backfill owner/name`. It adopts the issues on that "
+            + "repository that the board does not already link.");
+    }
+    if (parseRepo(repo) === undefined) {
+        throw usageError(`"${repo}" is not a GitHub repository. Expected owner/name, e.g. contoso/widgets — `
+            + "backfill takes a whole repository, not one issue.", { given: repo });
+    }
+    const state = issueStateFilter(options.state);
+    const github = await session.github();
+    const binding = github.binding(repo);
+    // The board first: it is the cheap half, and it is what makes deciding
+    // "already adopted" cost two requests instead of one per issue.
+    const linked = linkedNumbersIn(await scanBoardLinks(session, options), repo);
+    const sweep = await github.issues.list(binding, {
+        state,
+        ...(options.labels.length === 0 ? {} : { labels: options.labels }),
+    });
+    const candidates = backfillCandidates(sweep.issues.map((issue) => ({
+        number: issue.number,
+        title: issue.title,
+        state: issue.state,
+        url: issue.htmlUrl,
+        updatedAt: issue.updatedAt,
+    })), linked);
+    const limit = options.limit ?? candidates.length;
+    const chosen = candidates.slice(0, limit);
+    const needed = chosen.length * WRITES_PER_ADOPTION;
+    const target = {
+        repo: binding.repo,
+        // Named because nothing in the design pairs a repository with a board (#807)
+        // and on a machine with two clients configured nothing would say a word.
+        // One mis-aimed `adopt` is one work item; one mis-aimed `backfill --yes` is
+        // four hundred, each with a public comment naming a board its reporter has
+        // nothing to do with. So the pairing is on screen before `--yes`.
+        account: binding.account,
+        organization: session.client.organization,
+        project: session.client.project ?? null,
+    };
+    const preview = {
+        repo: binding.repo,
+        target,
+        issues: {
+            swept: sweep.issues.length,
+            // From `gh-core`, which filters them at the boundary: every pull request
+            // is an issue on that endpoint, and an unfiltered backfill would file work
+            // items for the whole PR history.
+            pullRequestsSkipped: sweep.pullRequestsSkipped,
+            state,
+            ...(options.labels.length === 0 ? {} : { labels: options.labels }),
+            alreadyLinked: linked.size,
+            candidates: candidates.length,
+        },
+        wouldAdopt: chosen.length,
+        ...(options.limit === undefined ? {} : { limit: options.limit }),
+        writes: {
+            needed,
+            perAdoption: WRITES_PER_ADOPTION,
+            budget: session.budget.limit,
+            remaining: session.budget.remaining,
+        },
+        candidates: chosen.map((candidate) => ({
+            number: candidate.number,
+            title: candidate.title,
+            state: candidate.state,
+            url: candidate.url,
+        })),
+    };
+    if (chosen.length === 0) {
+        return report(io, session, {
+            applied: false,
+            unchanged: true,
+            ...preview,
+            message: candidates.length === 0
+                ? `Nothing to backfill: all ${sweep.issues.length} issues on ${binding.repo} matching `
+                    + `state=${state} are already linked from the board.`
+                : `--limit ${String(options.limit)} selected nothing.`,
+        });
+    }
+    const stop = approve(io, session, {
+        what: `adopt ${chosen.length} issue${chosen.length === 1 ? "" : "s"} from ${binding.repo} onto `
+            + `${session.client.project ?? "this project"} — ${needed} writes, and a public comment on `
+            + `each issue`,
+        would: preview,
+    });
+    if (stop !== undefined)
+        return stop;
+    // Refused BEFORE the first write rather than discovered at the last one. A run
+    // that stops halfway is recoverable, but it is the outcome a caller can reason
+    // about least, and the two ways forward are both one flag.
+    if (needed > session.budget.remaining) {
+        throw refusal(`Adopting ${chosen.length} issues costs ${needed} writes and this invocation has `
+            + `${session.budget.remaining} left of ${session.budget.limit}. Nothing was written.`, {
+            ...preview,
+            hint: `Either raise the cap — \`--max-writes ${needed}\` — or take it in bites with `
+                + `\`--limit ${Math.max(1, Math.floor(session.budget.remaining / WRITES_PER_ADOPTION))}\`. `
+                + "Running it again later resumes where it stopped: the link itself is the progress "
+                + "record, so an adopted issue is simply no longer a candidate.",
+        });
+    }
+    const parent = options.parent === undefined ? undefined : await resolveParent(session, options.parent);
+    const type = options.type ?? DEFAULT_WORK_ITEM_TYPE;
+    const adopted = [];
+    const skipped = [];
+    const failed = [];
+    let stopped;
+    for (const candidate of chosen) {
+        const ref = { ...binding, number: candidate.number };
+        const coordinate = { repo: binding.repo, number: candidate.number };
+        try {
+            const outcome = await adoptOne(session, ref, coordinate, { type, parent, title: options.title });
+            if (outcome.skipped !== undefined) {
+                skipped.push(outcome.skipped);
+                continue;
+            }
+            adopted.push(outcome.adopted);
+        }
+        catch (error) {
+            const { kind, body } = failureOf(error);
+            const row = {
+                issue: formatIssueCoordinate(coordinate),
+                number: candidate.number,
+                kind,
+                message: String(body["message"] ?? error),
+                // Carried up verbatim when the adoption half-happened: the work item
+                // exists, and a work item nobody can name is worse than a failed call.
+                ...(body["createdWorkItem"] === undefined
+                    ? {}
+                    : { createdWorkItem: body["createdWorkItem"], halfLinked: true, recover: body["recover"] }),
+            };
+            failed.push(row);
+            // **Stop on the failures that will repeat, carry on past the ones that are
+            // about one issue.** A bad PAT, an exhausted budget and an hourly rate
+            // limit are all true of the next three hundred issues too, so continuing
+            // is three hundred identical errors and a longer wait for the same answer.
+            // A 404 or a validation refusal is about this issue, and skipping past it
+            // is what a bulk verb is for.
+            if (WILL_REPEAT.has(kind)) {
+                stopped = { after: adopted.length + skipped.length + failed.length, reason: kind, kindMessage: String(body["message"] ?? "") };
+                break;
+            }
+        }
+    }
+    const done = adopted.length + skipped.length;
+    const remaining = candidates.length - done;
+    const resume = `pharos issue backfill ${binding.repo}`
+        + (state === "open" ? "" : ` --state ${state}`)
+        + options.labels.map((label) => ` --label ${label}`).join("")
+        + (options.parent === undefined ? "" : ` --parent ${String(options.parent)}`)
+        + " --yes";
+    return report(io, session, {
+        applied: true,
+        repo: binding.repo,
+        target,
+        adopted,
+        skipped,
+        failed,
+        stopped: stopped ?? null,
+        counts: {
+            adopted: adopted.length,
+            skipped: skipped.length,
+            failed: failed.length,
+            remaining: Math.max(0, remaining),
+        },
+        // Only when there is something left, so its presence means "there is more"
+        // rather than being a line every caller has to interpret.
+        ...(remaining > 0 ? { resume } : {}),
+    });
+}
+/**
+ * Failure kinds that are about the *run* rather than about one issue.
+ *
+ * Everything here is equally true of every remaining candidate, so continuing
+ * would spend three hundred more requests to be told the same thing.
+ */
+const WILL_REPEAT = new Set(["auth", "config", "refused", "rateLimit", "network", "usage"]);
+/**
+ * One issue, adopted or found already adopted.
+ *
+ * The marker read is the reason this is not just {@link performAdoption}: the
+ * board's hyperlink index cannot see a link whose Azure DevOps end was deleted
+ * by hand, and adopting over the top of one would put a second work item on an
+ * issue that already names one. `adopt` makes the same check for the same
+ * reason; here it is paid only for the issues actually being written.
+ */
+async function adoptOne(session, ref, coordinate, options) {
+    const github = await session.github();
+    const issue = await github.issues.get(ref);
+    const comments = await github.issues.comments(ref);
+    // `linksFromComments` + `mergeLinks` already collapse many marked comments to
+    // one row per pair, so this ASKS whether the issue is claimed rather than
+    // counting comments: `pharos issue say` posts a marked comment on every
+    // invocation, and an issue can legitimately carry a dozen naming one work item
+    // (#784).
+    const existing = linksFromComments(coordinate, comments);
+    const claimed = [...new Set(existing.map((link) => link.workItemId))];
+    if (claimed.length > 0) {
+        return {
+            skipped: {
+                issue: formatIssueCoordinate(coordinate),
+                number: coordinate.number,
+                reason: "already-adopted",
+                workItemIds: claimed,
+                detail: claimed.length === 1
+                    ? `Already adopted as #${claimed[0]} — the board's link to it is missing, so `
+                        + `\`pharos issue link ${formatIssueCoordinate(coordinate)} ${claimed[0]}\` is the `
+                        + "repair. Creating a second work item is not."
+                    : `Carries markers for ${claimed.length} different work items (${claimed.join(", ")}); `
+                        + "resolve which one is right before adopting anything here.",
+            },
+        };
+    }
+    const title = options.title ?? issue.title;
+    const outcome = await performAdoption(session, ref, {
+        type: options.type,
+        title,
+        ops: adoptionOps(issue, { title, parent: options.parent }),
+    });
+    return {
+        adopted: {
+            issue: formatIssueCoordinate(coordinate),
+            number: coordinate.number,
+            title: issue.title,
+            state: issue.state,
+            workItem: { id: outcome.workItemId, type: options.type, title, url: outcome.workItemUrl },
+            commentUrl: outcome.commentUrl,
+        },
+    };
+}
+/** The board's whole link index — shared with `drift`, which is what it is for. */
+async function scanBoardLinks(session, options) {
+    const statement = options.wiql ?? driftWiql();
+    let items;
+    try {
+        items = await session.client.wiql.queryAndFetch(statement, { expand: "relations" });
+    }
+    catch (error) {
+        throw explainScanFailure(error, statement, options.wiql !== undefined);
+    }
+    return linksOnWorkItems(items, (item) => describeWorkItem(session, item), (item) => linksFromHyperlinks(item.id, hyperlinkUrls(item)));
+}
+/** `--state`, or the default and the argument for it. */
+function issueStateFilter(given) {
+    const value = given?.trim().toLowerCase();
+    if (value === undefined || value === "") {
+        // **Open, not all.** The premise of this verb is a repository with four
+        // hundred *open* issues; a closed one is history, and adopting it creates a
+        // work item that is finished before anybody looks at it. `--state all` is
+        // there for the migration that genuinely wants the archive.
+        return "open";
+    }
+    if (value === "open" || value === "closed" || value === "all")
+        return value;
+    throw usageError(`--state must be open, closed or all; got "${given}".`, { given });
+}
+// MARK: - close
+/**
+ * `pharos issue close <id|owner/name#45>` — the ending of the workflow, and the
+ * one verb the plan's table listed that nothing had built.
+ *
+ * The value this whole feature claims (§1) is *"an issue is reported → picked up
+ * as a work item → worked → commented on both sides in the register each
+ * audience needs → **closed on both, each closure pointing at the other**"*.
+ * Every arrow before the last one shipped. Without this the product has no way
+ * to finish the thing it was built to start.
+ *
+ * ## Why this closes rather than composing a PR body
+ *
+ * §13.3 says Pharos's job is *"composing that body and verifying it fired rather
+ * than doing the closing"* — and that sentence is inside **Decisions still
+ * open**, under an item whose first four words are "Out of scope for v1". The
+ * magic words only fire from a **PR merge**: §1 is explicit that the transition
+ * "fires from a commit or a PR merge, never from closing an issue". With pull
+ * requests out of scope there is no body to compose into, so a verb built that
+ * way would verify a transition nothing had triggered and report "neither end
+ * closed" every single time.
+ *
+ * The instinct behind it is still right, and it lands in two places:
+ *
+ * 1. **Which terminal state is asked, never assumed.** There is no hardcodable
+ *    `Closed` — see `terminalStateFor`. Several terminal states is a refusal
+ *    naming them and `--to`, not a guess between `Done` and `Removed`.
+ * 2. **Both ends are re-read after the writes.** Two 200s are not proof: a
+ *    state transition can be refused by a rule the API reports as success on the
+ *    field it did apply, and `report.verified` is what was actually there
+ *    afterwards rather than what was sent.
+ *
+ * ## No `--yes`
+ *
+ * Closing is a state change and this CLI's gate is for what destroys or
+ * overwrites — `pharos update --state Done` needs no `--yes` either, and a close
+ * is reversible from both platforms. The one genuinely surprising case is
+ * guarded where the surprise is: a work item hyperlinking **several** issues is
+ * refused unless `--all` is passed, because "close #4821" reading as "close four
+ * strangers' issues" is not what anybody typed.
+ */
+async function runClose(io, session, positionals, options) {
+    const target = positionals[0];
+    if (target === undefined || target === "") {
+        throw usageError("Which pair? `pharos issue close 4821` or `pharos issue close owner/name#45`. It closes "
+            + "BOTH ends and says what did not move.");
+    }
+    // **Both of these are settled before a single call.** They are facts about
+    // what was typed, so spending a request to discover them is only slower — and
+    // worse, it reclassifies them: a bad `--reason` validated after the GitHub
+    // client resolves reports as a *config* error about `repos.json`, which sends
+    // an agent to fix a file that was never wrong.
+    const reason = closingReason(options.reason);
+    if (options.message !== undefined && isPharosAuthored(options.message)) {
+        throw refusal("That closing note already carries a pharos:v1 trailer, which means it is a comment Pharos "
+            + "wrote. The trailer is added on the way out; never pass one in.");
+    }
+    let catalog;
+    let catalogFailure;
+    try {
+        catalog = await session.client.workItemTypes.states();
+    }
+    catch (error) {
+        catalogFailure = error instanceof Error ? error.message : String(error);
+    }
+    const states = finishedStates(catalog, catalogFailure);
+    const pairs = await resolveClosePairs(session, target, options);
+    const results = [];
+    for (const pair of pairs) {
+        results.push(await closePair(io, session, pair, states, options, reason));
+    }
+    const moved = results.filter((row) => row["wrote"].length > 0).length;
+    const stuck = results.filter((row) => row["closed"] !== true);
+    return report(io, session, {
+        applied: moved > 0,
+        ...(moved === 0 ? { unchanged: true } : {}),
+        closed: results.filter((row) => row["closed"] === true).length,
+        // Named even at zero: "which ends did not move" is the whole deliverable of
+        // a verb whose table row reads "verify both ends closed; report what did not".
+        didNotClose: stuck.length,
+        pairs: results,
+    });
+}
+/**
+ * The pairs to close, from whichever end was named.
+ *
+ * From an **issue**, the one work item that claims it — `soleWorkItem` already
+ * refuses nothing and several, and both refusals are as right here as they are
+ * for `say`.
+ *
+ * From a **work item**, every issue it hyperlinks. One work item legitimately
+ * references several reported symptoms, and finishing the work does finish all
+ * of them — but closing four strangers' issues is not what `close 4821` looks
+ * like it does, so more than one needs `--all`.
+ */
+async function resolveClosePairs(session, target, options) {
+    const github = await session.github();
+    if (!/^\d+$/.test(target.trim())) {
+        const ref = await resolveIssue(session, target, "close");
+        const coordinate = { repo: ref.repo, number: ref.number };
+        const comments = await github.issues.comments(ref);
+        const workItemId = soleWorkItem(coordinate, linksFromComments(coordinate, comments));
+        const item = await session.client.workItems.get(workItemId, { expand: "relations" });
+        return [{ item, ref, coordinate }];
+    }
+    const id = Number(target.trim());
+    const item = await session.client.workItems.get(id, { expand: "relations" });
+    const links = linksFromHyperlinks(id, hyperlinkUrls(item));
+    if (links.length === 0) {
+        throw refusal(`Work item #${id} does not link any GitHub issue, so there is no other end to close. `
+            + `\`pharos update ${id} --state <state>\` closes the work item alone.`, { workItemId: id });
+    }
+    if (links.length > 1 && !options.all) {
+        throw refusal(`Work item #${id} links ${links.length} issues `
+            + `(${links.map((link) => `${link.repo}#${link.issueNumber}`).join(", ")}). Closing it `
+            + "would close all of them, on repositories that may not be ours — pass --all if that is "
+            + "what you mean, or close one at a time from the issue end.", {
+            workItemId: id,
+            issues: links.map((link) => `${link.repo}#${link.issueNumber}`),
+            hint: "`pharos issue trail` shows the whole trail first.",
+        });
+    }
+    return links.map((link) => {
+        const coordinate = { repo: link.repo, number: link.issueNumber };
+        return {
+            item,
+            ref: { ...github.binding(link.repo), number: link.issueNumber },
+            coordinate,
+        };
+    });
+}
+/**
+ * Close one pair, then look again.
+ *
+ * **Azure DevOps first**, matching `adopt` and `link` so there is one recovery
+ * path rather than three — and because the GitHub half is published on a
+ * repository that may not be ours. Neither closing comment depends on a URL the
+ * other write creates (unlike `say`, whose board comment carries the GitHub
+ * comment's anchor), so the order is free to be the consistent one.
+ *
+ * Each closure points at the other, which is §1's phrase and not decoration: the
+ * board comment names the issue, the issue comment names the work item, and a
+ * person landing on either end can reach the other without knowing this tool
+ * exists.
+ */
+async function closePair(io, session, pair, states, options, reason) {
+    void io;
+    const label = formatIssueCoordinate(pair.coordinate);
+    const workItemId = pair.item.id;
+    const workItemUrl = session.workItemUrl(pair.item);
+    const url = issueUrl(pair.coordinate);
+    const github = await session.github();
+    const issue = await github.issues.get(pair.ref);
+    const itemState = titleOfField(pair.item, "System.State");
+    const itemType = titleOfField(pair.item, "System.WorkItemType");
+    const alreadyFinished = isFinished(states, itemType, itemState);
+    const alreadyClosed = issue.state === "closed";
+    if (alreadyFinished && alreadyClosed) {
+        // Idempotent, like `adopt`. The state asked for already holds, and an agent
+        // that retries a call it cannot tell succeeded is the normal case.
+        return {
+            issue: label,
+            workItem: workItemId,
+            closed: true,
+            wrote: [],
+            unchanged: true,
+            verified: { workItem: { state: itemState, finished: true }, issue: { state: issue.state } },
+            message: `${label} and #${workItemId} are both already closed.`,
+        };
+    }
+    const targetState = alreadyFinished ? undefined : closingState(states, itemType, options);
+    if (session.previewOnly) {
+        return {
+            issue: label,
+            workItem: workItemId,
+            closed: false,
+            dryRun: true,
+            wrote: [],
+            wouldWrite: [
+                ...(alreadyFinished ? [] : ["work-item-state", "ado-comment"]),
+                ...(alreadyClosed ? [] : ["github-state", "github-comment"]),
+            ],
+            ...(targetState === undefined ? {} : { wouldMoveTo: targetState }),
+        };
+    }
+    const wrote = [];
+    if (!alreadyFinished && targetState !== undefined) {
+        // Guarded on the rev of the read this came from, like every other write
+        // here. A teammate's edit lands as a conflict rather than on top of — and
+        // `output.ts` already says out loud that a bare comment bumps System.Rev, so
+        // a mismatch is not proof of an edit collision.
+        await session.client.workItems.updateWithRev(workItemId, pair.item.rev, [
+            setField("System.State", targetState),
+        ]);
+        wrote.push("work-item-state");
+        await session.client.comments.add(workItemId, `Closed as **${targetState}** alongside [${label}](${url}), which was closed on GitHub.`
+            + (options.message === undefined ? "" : `\n\n${collapse(options.message)}`));
+        wrote.push("ado-comment");
+    }
+    if (!alreadyClosed) {
+        await github.issues.setState(pair.ref, { state: "closed", stateReason: reason });
+        wrote.push("github-state");
+        // Composed by `gh-core` so this and the macOS app produce the same bytes,
+        // and so the trailer travels with it — `isPharosAuthored` is total only if
+        // nothing anywhere posts an unmarked Pharos comment.
+        const body = composeLinkComment({
+            repo: pair.ref.repo,
+            issue: pair.ref.number,
+            adoId: workItemId,
+            workItemUrl,
+            workItemTitle: titleOf(pair.item) ?? undefined,
+            message: closingNote(options.message, reason),
+        });
+        await github.issues.comment(pair.ref, body);
+        wrote.push("github-comment");
+    }
+    // **Look again rather than trusting two 200s.** A state transition can be
+    // refused by a workflow rule on a field the API happily accepted, and the
+    // whole row this verb answers to reads "verify both ends closed; report what
+    // did not".
+    const after = await session.client.workItems.get(workItemId);
+    const afterIssue = await github.issues.get(pair.ref);
+    const finishedNow = isFinished(states, titleOfField(after, "System.WorkItemType"), titleOfField(after, "System.State"));
+    const closedNow = afterIssue.state === "closed";
+    return {
+        issue: label,
+        workItem: workItemId,
+        closed: finishedNow && closedNow,
+        wrote,
+        verified: {
+            workItem: { state: titleOfField(after, "System.State"), finished: finishedNow },
+            issue: { state: afterIssue.state, stateReason: afterIssue.stateReason ?? null },
+        },
+        ...(finishedNow && closedNow
+            ? {}
+            : {
+                didNotClose: [
+                    ...(finishedNow ? [] : ["work-item"]),
+                    ...(closedNow ? [] : ["issue"]),
+                ],
+                hint: "Both writes were accepted and one end is still open. That is usually a workflow rule "
+                    + "on the work item type — a required field, or a transition this state cannot make "
+                    + "directly. Nothing here retried it, because a rule will refuse it again.",
+            }),
+    };
+}
+/** `--to`, or the project's own answer, or a refusal saying which it could not pick. */
+function closingState(states, type, options) {
+    const given = options.to?.trim();
+    if (given !== undefined && given !== "")
+        return given;
+    const choice = terminalStateFor(states, type);
+    if (choice.kind === "one")
+        return choice.state;
+    if (choice.kind === "several") {
+        throw refusal(`${type ?? "This work item type"} has ${choice.states.length} finished states `
+            + `(${choice.states.join(", ")}) and they do not mean the same thing — "done" and `
+            + `"abandoned" are both closed. Name one with \`--to\`. Nothing was written.`, { states: choice.states, hint: `e.g. --to ${choice.states[0]}` });
+    }
+    if (choice.kind === "none") {
+        throw refusal(`${type ?? "This work item type"} has no state in a completed category, so there is nothing `
+            + "to close it into. Name one with `--to` if the process uses a state this catalogue does "
+            + "not categorise.");
+    }
+    throw refusal(`${states.note} Closing needs to WRITE a state name, and guessing one would either fail with `
+        + "a message about a field you did not name or land in a state nobody meant — so name it "
+        + "with `--to`.", { hint: "`pharos types` lists the states this project's work item types actually have." });
+}
+/** GitHub's `state_reason`. Two values matter and they are not interchangeable. */
+function closingReason(given) {
+    const value = given?.trim().toLowerCase().replace(/-/g, "_");
+    if (value === undefined || value === "")
+        return "completed";
+    if (value === "completed" || value === "not_planned")
+        return value;
+    throw usageError(`--reason must be completed or not-planned; got "${given}". GitHub renders them differently, `
+        + "and closing somebody's report as \"completed\" when it was declined is a worse lie than "
+        + "saying nothing.", { given });
+}
+/** The reporter's register: what happened, in words written for them. */
+function closingNote(message, reason) {
+    const opening = reason === "not_planned"
+        ? "Closing this as not planned."
+        : "Closing this — the work tracking it is done.";
+    const extra = message?.trim();
+    return extra === undefined || extra === "" ? opening : `${opening}\n\n${extra}`;
+}
+function titleOfField(item, name) {
+    const value = item.fields?.[name];
+    return typeof value === "string" && value !== "" ? value : null;
+}
+// MARK: - shared
+/**
+ * `owner/name#45` → everything needed to call GitHub about it.
+ *
+ * The account comes from `repos.json` and there is **no fallback to whichever
+ * `gh` account is active** (plan §2). On the machine this was designed on the
+ * active account was not the one owning the repository behind the project being
+ * worked, and two accounts can each see a repository of the same name — so
+ * guessing does not fail, it returns 200 for the wrong repository.
+ */
+async function resolveIssue(session, text, verb) {
+    if (text === undefined || text === "") {
+        throw usageError(`Which issue? \`pharos issue ${verb} owner/name#45\`.`);
+    }
+    const coordinate = assertIssueCoordinate(text);
+    const github = await session.github();
+    // Throws a `GitHubConfigError` naming the repo and the file when it is unbound
+    // — reported as `kind: "config"`, exit 2, because no retry can fix it.
+    const binding = github.binding(coordinate.repo);
+    return { ...binding, number: coordinate.number };
+}
+/**
+ * Post the Pharos comment: the sentence, the `AB#` mention and the trailer, all
+ * three composed by `gh-core` so this and the macOS app produce the same bytes.
+ *
+ * `createdWorkItem` is passed only by `adopt`, and only because by that point
+ * something exists that the error must name.
+ */
+async function postLinkComment(session, ref, options) {
+    const github = await session.github();
+    const body = composeLinkComment({
+        repo: ref.repo,
+        issue: ref.number,
+        adoId: options.workItemId,
+        workItemUrl: options.workItemUrl,
+        workItemTitle: options.workItemTitle,
+    });
+    try {
+        return await github.issues.comment(ref, body);
+    }
+    catch (error) {
+        const { kind, code, body: reported } = failureOf(error);
+        const coordinate = formatIssueCoordinate({ repo: ref.repo, number: ref.number });
+        const recover = `pharos issue link ${coordinate} ${options.workItemId}`;
+        const created = options.createdWorkItem;
+        throw new CliError((created === undefined
+            ? `The Azure DevOps end of the link to ${coordinate} is written and the GitHub comment is `
+                + "not"
+            : `Work item #${created} was CREATED, and the GitHub comment naming it was not posted`)
+            + `: ${String(reported["message"] ?? "")}`, kind, code, {
+            // Which side said no, kept at the top level rather than only inside
+            // `cause`: on a two-platform verb that is the first thing a caller needs,
+            // and the wrapping must not be where it gets lost.
+            platform: "github",
+            issue: { repo: ref.repo, number: ref.number },
+            workItemId: options.workItemId,
+            ...(created === undefined ? {} : { createdWorkItem: created }),
+            wrote: ["hyperlink"],
+            halfLinked: true,
+            recover,
+            hint: `Nothing needs undoing — re-run \`${recover}\` to write the missing half.`,
+            cause: reported,
+        });
+    }
+}
+/**
+ * The `Hyperlink` relation urls on a work item.
+ *
+ * Filtered by `rel` rather than handed the whole array, because layer 1 of the
+ * link IS a `Hyperlink` relation — a github.com issue URL arriving as some other
+ * relation kind would be a different fact, and reporting it as `evidence:
+ * ["hyperlink"]` would make the word mean two things.
+ */
+function hyperlinkUrls(item) {
+    const relations = item.relations ?? [];
+    return relations
+        .filter((relation) => relation.rel === "Hyperlink")
+        .map((relation) => relation.url)
+        .filter((url) => typeof url === "string" && url !== "");
+}
+function summariseWorkItem(session, item) {
+    const fields = item.fields ?? {};
+    const text = (name) => {
+        const value = fields[name];
+        return typeof value === "string" && value !== "" ? value : null;
+    };
+    return {
+        id: item.id,
+        type: text("System.WorkItemType"),
+        title: text("System.Title"),
+        state: text("System.State"),
+        assignedTo: displayName(fields["System.AssignedTo"]),
+        url: session.workItemUrl(item),
+    };
+}
+function summariseIssue(issue, coordinate) {
+    return {
+        repo: issue.repo,
+        number: issue.number,
+        title: issue.title,
+        state: issue.state,
+        stateReason: issue.stateReason ?? null,
+        author: issue.author ?? null,
+        updatedAt: issue.updatedAt,
+        comments: issue.commentCount,
+        url: issue.htmlUrl === "" ? issueUrl(coordinate) : issue.htmlUrl,
+    };
+}
+/** `null` rather than absent: unassigned is an answer, and a common one. */
+function displayName(value) {
+    if (typeof value === "string" && value !== "")
+        return value;
+    if (typeof value === "object" && value !== null) {
+        const display = value.displayName;
+        if (typeof display === "string")
+            return display;
+    }
+    return null;
+}
+function titleOf(item) {
+    const title = item.fields?.["System.Title"];
+    return typeof title === "string" ? title : null;
+}
+function workItemArgument(raw, usage) {
+    if (raw === undefined || raw === "")
+        throw usageError(usage);
+    if (!/^\d+$/.test(raw))
+        throw usageError(`"${raw}" is not a work item id.`, { given: raw });
+    return Number(raw);
+}
+function report(io, session, result) {
+    if (!session.pretty)
+        return emit(io, result);
+    return emitText(io, render(result));
+}
+function render(result) {
+    // Checked before `message`, because both of these carry one as a summary line
+    // and the rows underneath it are the answer rather than decoration.
+    if (result["drift"] !== undefined)
+        return renderDrift(result);
+    if (result["adopted"] !== undefined)
+        return renderBackfill(result);
+    if (result["pairs"] !== undefined)
+        return renderClose(result);
+    const message = result["message"];
+    if (typeof message === "string")
+        return message;
+    if (result["links"] !== undefined)
+        return renderTrail(result);
+    if (result["github"] !== undefined)
+        return renderSay(result);
+    const issue = result["issue"];
+    const workItem = result["workItem"];
+    const coordinate = `${String(issue?.["repo"] ?? "")}#${String(issue?.["number"] ?? "")}`;
+    const wrote = (result["wrote"] ?? result["wouldWrite"]);
+    const written = wrote === undefined || wrote.length === 0 ? "nothing" : wrote.join(" + ");
+    // A guard that could not run is the one thing on this path a person has to be
+    // told, and `--pretty` is the mode where nobody is reading the JSON that says
+    // so. Silence would read as "checked, and nothing was already tracking it".
+    const check = result["boardCheck"];
+    const unchecked = check?.["ran"] === false
+        ? "\n! the board was NOT checked for a work item that already links this issue — "
+            + String(check["problem"] ?? "")
+        : "";
+    if (result["dryRun"] === true) {
+        const id = workItem?.["id"];
+        const naming = id === undefined ? `a new ${String(workItem?.["type"] ?? "")}` : `#${String(id)}`;
+        return `would link ${coordinate} to ${naming} (${written})${unchecked}`;
+    }
+    return `${coordinate} ↔ #${String(workItem?.["id"] ?? "")} — wrote ${written}${unchecked}`;
+}
+/**
+ * Two lines for two audiences, because one line would flatten the only thing
+ * about this verb worth seeing at a glance.
+ */
+function renderSay(result) {
+    const issue = result["issue"];
+    const workItem = result["workItem"];
+    const github = result["github"];
+    const summary = result["summary"];
+    const coordinate = `${String(issue?.["repo"] ?? "")}#${String(issue?.["number"] ?? "")}`;
+    const id = `#${String(workItem?.["id"] ?? "")}`;
+    if (result["dryRun"] === true) {
+        return `would tell ${coordinate} in full and summarise it on ${id} — nothing written`;
+    }
+    return [
+        `told ${coordinate} — ${String(github?.["commentUrl"] ?? "")}`,
+        `summarised on ${id} — ${String(summary?.["text"] ?? "")}`,
+    ].join("\n");
+}
+/**
+ * Drift, one row per finding, and a headline that says what was *not* wrong.
+ *
+ * The healthy count leads because it is what makes the findings readable: "3
+ * problems" is alarming out of nowhere and unremarkable out of two hundred
+ * links. `truncated` is on the same line for the same reason — "the board is
+ * clean" and "the first twenty were clean" must not print identically.
+ */
+function renderDrift(result) {
+    const rows = (result["drift"] ?? []);
+    const scanned = (result["scanned"] ?? {});
+    const examined = Number(scanned["examined"] ?? 0);
+    const healthy = Number(result["healthy"] ?? 0);
+    const cut = scanned["truncated"] === true ? ` of ${String(scanned["links"])} — TRUNCATED by --limit` : "";
+    const head = rows.length === 0
+        ? `${examined} link${examined === 1 ? "" : "s"}${cut}, none drifting`
+        : `${rows.length} of ${examined} link${examined === 1 ? "" : "s"}${cut} drifting `
+            + `(${healthy} healthy)`;
+    const states = (result["finishedStates"] ?? {});
+    const basis = states["source"] === "fallback"
+        ? "\n! finished states were GUESSED — this project's catalogue could not be read, so a state "
+            + "row here may be wrong"
+        : "";
+    if (rows.length === 0)
+        return head + basis;
+    return [
+        head + basis,
+        ...rows.map((row) => {
+            const workItem = (row["workItem"] ?? {});
+            const kind = String(row["kind"]);
+            const where = `${String(row["coordinate"])} ↔ #${String(workItem["id"])}`;
+            return `  ${kind.padEnd(13)} ${where}\n      ${String(row["detail"])}`
+                + (row["recover"] === undefined ? "" : `\n      fix: ${String(row["recover"])}`);
+        }),
+    ].join("\n");
+}
+/**
+ * What closed, and — the part that matters — what did not.
+ *
+ * The verified state is printed rather than the state that was sent, because the
+ * whole reason this verb re-reads is that those two can differ.
+ */
+function renderClose(result) {
+    const pairs = (result["pairs"] ?? []);
+    return pairs
+        .map((pair) => {
+        const verified = (pair["verified"] ?? {});
+        const workItem = (verified["workItem"] ?? {});
+        const issue = (verified["issue"] ?? {});
+        const where = `${String(pair["issue"])} ↔ #${String(pair["workItem"])}`;
+        if (pair["dryRun"] === true) {
+            const would = (pair["wouldWrite"] ?? []);
+            return would.length === 0
+                ? `${where} — already closed on both`
+                : `would close ${where} (${would.join(" + ")})`;
+        }
+        if (pair["closed"] === true) {
+            const wrote = (pair["wrote"] ?? []);
+            return wrote.length === 0
+                ? `${where} — already closed on both`
+                : `closed ${where} — ${String(workItem["state"] ?? "")} / ${String(issue["state"] ?? "")}`;
+        }
+        return (`DID NOT CLOSE ${where} — ${(pair["didNotClose"] ?? []).join(" and ")}`
+            + ` still open (${String(workItem["state"] ?? "")} / ${String(issue["state"] ?? "")})`);
+    })
+        .join("\n");
+}
+/** What a backfill did, or would do. One line per issue is too many at 400. */
+function renderBackfill(result) {
+    const counts = (result["counts"] ?? {});
+    const stopped = result["stopped"];
+    const lines = [
+        `adopted ${String(counts["adopted"] ?? 0)} from ${String(result["repo"] ?? "")}`
+            + ` — ${String(counts["skipped"] ?? 0)} already linked, ${String(counts["failed"] ?? 0)} failed`,
+    ];
+    if (stopped !== null && stopped !== undefined) {
+        lines.push(`STOPPED after ${String(stopped["after"])}: ${String(stopped["reason"])}`);
+    }
+    if (result["resume"] !== undefined) {
+        lines.push(`${String(counts["remaining"] ?? 0)} left — ${String(result["resume"])}`);
+    }
+    return lines.join("\n");
+}
+function renderTrail(result) {
+    const links = (result["links"] ?? []);
+    if (links.length === 0) {
+        const anchor = (result["workItem"] ?? result["issue"]);
+        const name = anchor?.["id"] === undefined
+            ? `${String(anchor?.["repo"] ?? "")}#${String(anchor?.["number"] ?? "")}`
+            : `#${String(anchor["id"])}`;
+        return `${name} — no counterpart on the other platform`;
+    }
+    return links
+        .map((link) => {
+        const issue = link["issue"];
+        const workItem = link["workItem"];
+        const left = issue === null
+            ? "(unreadable)"
+            : `${String(issue["repo"])}#${String(issue["number"])} ${String(issue["state"])}`;
+        const right = workItem === null
+            ? "(unreadable)"
+            : `#${String(workItem["id"])} ${String(workItem["state"] ?? "")}`.trim();
+        const evidence = (link["evidence"] ?? []).join("+");
+        const problem = link["problem"];
+        const tail = typeof problem === "string" ? ` — ${problem}` : "";
+        return `${left} ↔ ${right}  [${evidence}]${tail}`;
+    })
+        .join("\n");
+}
+//# sourceMappingURL=issue.js.map