balladeer 0.0.4 → 1.0.0

package/dist/gh.js

@@ -0,0 +1,188 @@
+import { execFile } from "node:child_process";
+/**
+ * The person's own GitHub access, used through the tool they already signed in
+ * to. Balladeer holds no GitHub token and this command never sends one anywhere.
+ *
+ * Every call goes through `execFile` with an argument array, never a shell, so
+ * nothing here can be turned into a command by a repository name. Standard error
+ * is captured rather than inherited, because a `gh` failure has to become one
+ * plain sentence with a next action rather than provider noise in the middle of
+ * a step.
+ */
+const TIMEOUT_MS = 20_000;
+export function runCommand(file, args, options = {}) {
+    return new Promise((done) => {
+        execFile(file, [...args], {
+            ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+            ...(options.env === undefined ? {} : { env: { ...options.env } }),
+            timeout: options.timeoutMs ?? TIMEOUT_MS,
+            maxBuffer: 4 * 1024 * 1024,
+            windowsHide: true,
+        }, (error, stdout, stderr) => {
+            const code = error === null ? 0 : typeof error.code === "number" ? error.code : 1;
+            done({
+                ok: error === null,
+                code,
+                stdout: String(stdout),
+                // Bounded: a refusal is a sentence, never a page of output.
+                stderr: String(stderr).trim().slice(0, 500),
+            });
+        });
+    });
+}
+function readFacts(raw, authenticated) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    const id = typeof parsed.id === "number" ? String(parsed.id) : undefined;
+    const ownerId = typeof parsed.owner?.id === "number" ? String(parsed.owner.id) : undefined;
+    const branch = typeof parsed.default_branch === "string" ? parsed.default_branch : undefined;
+    if (!id || !ownerId || !branch)
+        return undefined;
+    // GitHub returns `permissions` only for an authenticated request, so its
+    // absence is exactly the case where nothing was proved about the caller.
+    const canWrite = parsed.permissions?.admin === true || parsed.permissions?.push === true;
+    return {
+        githubRepositoryId: id,
+        githubOwnerId: ownerId,
+        defaultBranch: branch,
+        canWrite,
+        authenticated,
+    };
+}
+export async function ghAvailable() {
+    return (await runCommand("gh", ["--version"])).ok;
+}
+export async function ghSignedIn() {
+    return (await runCommand("gh", ["auth", "status"])).ok;
+}
+/**
+ * Reads a repository's immutable ids, its default branch, and what the person
+ * may do with it.
+ *
+ * The unauthenticated read is deliberately NOT a fallback for enrolling. It
+ * proves nothing about who is asking, so a workspace could otherwise end up
+ * holding an enrollment, a CI identity, and eventually a protection claim about
+ * a repository nobody in it controls. It exists only so the command can render
+ * the do-it-by-hand block with real values.
+ */
+export async function readRepositoryFacts(repository) {
+    if (await ghAvailable()) {
+        if (!(await ghSignedIn())) {
+            return {
+                kind: "unavailable",
+                reason: "gh is installed but not signed in",
+                next: "Run `gh auth login`, then run this command again.",
+            };
+        }
+        const answer = await runCommand("gh", ["api", `repos/${repository}`]);
+        if (answer.ok) {
+            const facts = readFacts(answer.stdout, true);
+            if (facts)
+                return { kind: "found", facts };
+            return {
+                kind: "unavailable",
+                reason: "GitHub's answer did not carry the repository's ids",
+                next: "Check that the name is right and that GitHub is reachable, then run this command again.",
+            };
+        }
+        return {
+            kind: "unavailable",
+            reason: answer.stderr || `gh could not read repos/${repository}`,
+            next: `Check that ${repository} exists and that your GitHub account can see it, then run this command again.`,
+        };
+    }
+    return {
+        kind: "unavailable",
+        reason: "the GitHub CLI is not installed",
+        next: "Install the GitHub CLI from https://cli.github.com, sign in with `gh auth login`, then run this command again.",
+    };
+}
+/**
+ * The public read is a display convenience with no next action of its own: the
+ * caller is already printing the by-hand block, and this only fills its values.
+ */
+const PUBLIC_NEXT = "Add the repository by hand instead.";
+/** The public read, for rendering the fallback block only. */
+export async function readPublicRepositoryFacts(repository) {
+    let response;
+    try {
+        response = await fetch(`https://api.github.com/repos/${repository}`, {
+            headers: { accept: "application/vnd.github+json" },
+            redirect: "manual",
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+    }
+    catch {
+        return { kind: "unavailable", reason: "GitHub could not be reached", next: PUBLIC_NEXT };
+    }
+    if (!response.ok) {
+        return {
+            kind: "unavailable",
+            reason: `GitHub answered ${response.status}`,
+            next: PUBLIC_NEXT,
+        };
+    }
+    const facts = readFacts(await response.text(), false);
+    return facts === undefined
+        ? {
+            kind: "unavailable",
+            reason: "GitHub's answer did not carry the repository's ids",
+            next: PUBLIC_NEXT,
+        }
+        : { kind: "found", facts };
+}
+const WRITE_PERMISSIONS = new Set(["ADMIN", "MAINTAIN", "WRITE"]);
+function readRepositoryList(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const rows = [];
+    for (const entry of parsed) {
+        const name = typeof entry?.nameWithOwner === "string" ? entry.nameWithOwner : undefined;
+        if (name === undefined || entry.isArchived === true)
+            continue;
+        const permission = typeof entry.viewerPermission === "string" ? entry.viewerPermission.toUpperCase() : "";
+        rows.push({ repository: name, canWrite: WRITE_PERMISSIONS.has(permission) });
+    }
+    return rows;
+}
+/**
+ * The repositories one GitHub account or organization holds, newest first.
+ *
+ * `owner` empty means the signed-in account's own. A refusal is an empty list
+ * rather than an error: this is a convenience for offering a choice, and a
+ * person who cannot list an organization can still name a repository by hand.
+ */
+export async function listVisibleRepositories(owner, limit = 100) {
+    const answer = await runCommand("gh", [
+        "repo",
+        "list",
+        ...(owner === undefined ? [] : [owner]),
+        "--limit",
+        String(limit),
+        "--no-archived",
+        "--json",
+        "nameWithOwner,isArchived,viewerPermission",
+    ]);
+    return answer.ok ? readRepositoryList(answer.stdout) : [];
+}
+/** The signed-in GitHub account's login, or nothing. */
+export async function ghLogin() {
+    const answer = await runCommand("gh", ["api", "user", "--jq", ".login"]);
+    const login = answer.stdout.trim();
+    return answer.ok && /^[A-Za-z0-9-]{1,39}$/.test(login) ? login : undefined;
+}
+export async function setRepositoryVariable(repository, name, value) {
+    return runCommand("gh", ["variable", "set", name, "--repo", repository, "--body", value]);
+}

package/dist/git.d.ts

@@ -0,0 +1,76 @@
+export declare const CI_BRANCH = "balladeer/connect-ci";
+export declare function repositoryRoot(cwd: string): Promise<string | undefined>;
+/**
+ * A repository in the middle of a merge or a rebase is not a repository to open
+ * a pull request from. The person is mid-operation, and anything this command
+ * does to it will land in the middle of that work.
+ */
+export declare function midOperation(root: string): Promise<boolean>;
+export type BranchResult = Readonly<{
+    kind: "opened";
+    pullRequestUrl: string | undefined;
+}>
+/**
+ * The branch was already open with a pull request on it, and now carries the
+ * new bytes. This is what a release move looks like where the first pull
+ * request has not merged yet: one pull request that moves, rather than a
+ * second one competing to change the same file.
+ */
+ | Readonly<{
+    kind: "updated";
+    pullRequestUrl: string | undefined;
+}>
+/** The branch already carries these exact bytes, so there was nothing to commit. */
+ | Readonly<{
+    kind: "unchanged";
+}> | Readonly<{
+    kind: "refused";
+    reason: string;
+}>;
+/** The one-line subject of the commit and the pull request this branch carries. */
+export declare const CI_COMMIT_SUBJECT = "Connect Balladeer CI";
+/**
+ * The workflow as the default branch currently has it, fetched fresh.
+ *
+ * This is what tells a re-run that the pull request was merged. GitHub deletes
+ * the head branch on merge in most repositories, so looking for that branch
+ * answers "no" for a repository where the work is finished, and the command
+ * would go on to cut the branch again, write identical bytes, and be told by git
+ * that there is nothing to commit. A person would then read an instruction to
+ * commit a file that is already on their default branch.
+ */
+export declare function workflowOnDefaultBranch(root: string, defaultBranch: string, workflowPath: string): Promise<string | undefined>;
+/**
+ * Commits ONE file on a branch cut from the freshly fetched default branch, in a
+ * throwaway worktree.
+ *
+ * Three properties, each the answer to a way this could have gone wrong:
+ *
+ * - The branch is cut from `origin/<default branch>` as just fetched, never from
+ *   whatever HEAD happens to be. A developer sitting on a feature branch would
+ *   otherwise open a pull request carrying every local commit they had not
+ *   pushed, including anything they had not meant to. Where the branch is
+ *   already open on the remote it is BUILT ON instead, so a second commit lands
+ *   on the pull request the reviewer is already looking at. Re-cutting it from
+ *   the default branch would rewrite a pushed branch, which the remote refuses,
+ *   and forcing past that refusal would discard whatever the reviewer had asked
+ *   for on it.
+ * - It is a separate worktree, so the developer's own checkout is never switched,
+ *   never stashed, and never left on a branch they did not ask for. Their
+ *   uncommitted work stays exactly where it was.
+ * - The commit names its path explicitly. The `.mcp.json` and instructions
+ *   changes from the previous step stay in the developer's working tree for them
+ *   to commit deliberately: a pull request titled "Connect Balladeer CI" must
+ *   contain the CI change and nothing else, because its reviewer is approving
+ *   what they can see.
+ */
+export declare function commitWorkflowOnBranch(input: {
+    root: string;
+    defaultBranch: string;
+    workflowPath: string;
+    workflowYaml: string;
+    repository: string;
+    bodyPath: string;
+    /** What the commit and any new pull request are called. */
+    subject?: string;
+}): Promise<BranchResult>;

package/dist/git.js

@@ -0,0 +1,203 @@
+import { existsSync } from "node:fs";
+import { mkdtempSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { runCommand } from "./gh.js";
+export const CI_BRANCH = "balladeer/connect-ci";
+export async function repositoryRoot(cwd) {
+    const answer = await runCommand("git", ["-C", cwd, "rev-parse", "--show-toplevel"]);
+    return answer.ok ? answer.stdout.trim() : undefined;
+}
+async function gitDirectory(root) {
+    const answer = await runCommand("git", ["-C", root, "rev-parse", "--absolute-git-dir"]);
+    return answer.ok ? answer.stdout.trim() : undefined;
+}
+/**
+ * A repository in the middle of a merge or a rebase is not a repository to open
+ * a pull request from. The person is mid-operation, and anything this command
+ * does to it will land in the middle of that work.
+ */
+export async function midOperation(root) {
+    const directory = await gitDirectory(root);
+    if (directory === undefined)
+        return false;
+    return ["MERGE_HEAD", "rebase-merge", "rebase-apply", "CHERRY_PICK_HEAD"].some((marker) => existsSync(join(directory, marker)));
+}
+/** The one-line subject of the commit and the pull request this branch carries. */
+export const CI_COMMIT_SUBJECT = "Connect Balladeer CI";
+/**
+ * The workflow as the default branch currently has it, fetched fresh.
+ *
+ * This is what tells a re-run that the pull request was merged. GitHub deletes
+ * the head branch on merge in most repositories, so looking for that branch
+ * answers "no" for a repository where the work is finished, and the command
+ * would go on to cut the branch again, write identical bytes, and be told by git
+ * that there is nothing to commit. A person would then read an instruction to
+ * commit a file that is already on their default branch.
+ */
+export async function workflowOnDefaultBranch(root, defaultBranch, workflowPath) {
+    const fetched = await runCommand("git", ["-C", root, "fetch", "origin", defaultBranch]);
+    if (!fetched.ok)
+        return undefined;
+    const shown = await runCommand("git", ["-C", root, "show", `FETCH_HEAD:${workflowPath}`]);
+    return shown.ok ? shown.stdout : undefined;
+}
+/**
+ * Commits ONE file on a branch cut from the freshly fetched default branch, in a
+ * throwaway worktree.
+ *
+ * Three properties, each the answer to a way this could have gone wrong:
+ *
+ * - The branch is cut from `origin/<default branch>` as just fetched, never from
+ *   whatever HEAD happens to be. A developer sitting on a feature branch would
+ *   otherwise open a pull request carrying every local commit they had not
+ *   pushed, including anything they had not meant to. Where the branch is
+ *   already open on the remote it is BUILT ON instead, so a second commit lands
+ *   on the pull request the reviewer is already looking at. Re-cutting it from
+ *   the default branch would rewrite a pushed branch, which the remote refuses,
+ *   and forcing past that refusal would discard whatever the reviewer had asked
+ *   for on it.
+ * - It is a separate worktree, so the developer's own checkout is never switched,
+ *   never stashed, and never left on a branch they did not ask for. Their
+ *   uncommitted work stays exactly where it was.
+ * - The commit names its path explicitly. The `.mcp.json` and instructions
+ *   changes from the previous step stay in the developer's working tree for them
+ *   to commit deliberately: a pull request titled "Connect Balladeer CI" must
+ *   contain the CI change and nothing else, because its reviewer is approving
+ *   what they can see.
+ */
+export async function commitWorkflowOnBranch(input) {
+    const subject = input.subject ?? CI_COMMIT_SUBJECT;
+    if (await midOperation(input.root)) {
+        return {
+            kind: "refused",
+            reason: "this repository is in the middle of a merge or rebase",
+        };
+    }
+    const fetched = await runCommand("git", [
+        "-C",
+        input.root,
+        "fetch",
+        "origin",
+        input.defaultBranch,
+    ]);
+    if (!fetched.ok) {
+        return {
+            kind: "refused",
+            reason: fetched.stderr || `git could not fetch ${input.defaultBranch}`,
+        };
+    }
+    const defaultHead = await runCommand("git", ["-C", input.root, "rev-parse", "FETCH_HEAD"]);
+    if (!defaultHead.ok) {
+        return {
+            kind: "refused",
+            reason: defaultHead.stderr || `git could not read ${input.defaultBranch}`,
+        };
+    }
+    // Resolved to an explicit commit, because the second fetch below moves
+    // FETCH_HEAD and the branch has to be cut from one of the two deliberately.
+    let base = defaultHead.stdout.trim();
+    const existingBranch = await runCommand("git", ["-C", input.root, "fetch", "origin", CI_BRANCH]);
+    if (existingBranch.ok) {
+        const branchHead = await runCommand("git", ["-C", input.root, "rev-parse", "FETCH_HEAD"]);
+        if (branchHead.ok)
+            base = branchHead.stdout.trim();
+    }
+    const worktree = join(mkdtempSync(join(tmpdir(), "balladeer-ci-")), "tree");
+    const added = await runCommand("git", [
+        "-C",
+        input.root,
+        "worktree",
+        "add",
+        "-B",
+        CI_BRANCH,
+        worktree,
+        base,
+    ]);
+    if (!added.ok) {
+        return { kind: "refused", reason: added.stderr || "git could not create a working branch" };
+    }
+    try {
+        const file = join(worktree, input.workflowPath);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, input.workflowYaml, { encoding: "utf8", mode: 0o644 });
+        const staged = await runCommand("git", ["-C", worktree, "add", "--", input.workflowPath]);
+        if (!staged.ok)
+            return { kind: "refused", reason: staged.stderr || "git could not stage the workflow" };
+        // Nothing staged means the branch already carries these exact bytes. That is
+        // a finished state, not a failure, and committing is what git would refuse.
+        const pending = await runCommand("git", [
+            "-C",
+            worktree,
+            "diff",
+            "--cached",
+            "--quiet",
+            "--",
+            input.workflowPath,
+        ]);
+        if (pending.ok)
+            return { kind: "unchanged" };
+        const committed = await runCommand("git", [
+            "-C",
+            worktree,
+            "-c",
+            "commit.gpgsign=false",
+            "commit",
+            "-m",
+            subject,
+            "--",
+            input.workflowPath,
+        ]);
+        if (!committed.ok) {
+            return { kind: "refused", reason: committed.stderr || "git could not commit the workflow" };
+        }
+        const pushed = await runCommand("git", ["-C", worktree, "push", "-u", "origin", CI_BRANCH]);
+        if (!pushed.ok) {
+            return { kind: "refused", reason: pushed.stderr || `git could not push ${CI_BRANCH}` };
+        }
+        // Only where the branch was already on the remote is there a pull request to
+        // find. Asking on a branch this run just created would be one GitHub call
+        // whose answer is always "none".
+        if (existingBranch.ok) {
+            const open = await runCommand("gh", [
+                "pr",
+                "list",
+                "--repo",
+                input.repository,
+                "--head",
+                CI_BRANCH,
+                "--state",
+                "open",
+                "--json",
+                "url",
+                "--jq",
+                ".[0].url",
+            ]);
+            const url = /(https:\/\/[^\s]*\/pull\/\d+)/.exec(open.ok ? open.stdout : "");
+            if (url)
+                return { kind: "updated", pullRequestUrl: url[1] };
+        }
+        const opened = await runCommand("gh", [
+            "pr",
+            "create",
+            "--repo",
+            input.repository,
+            "--base",
+            input.defaultBranch,
+            "--head",
+            CI_BRANCH,
+            "--title",
+            subject,
+            "--body-file",
+            input.bodyPath,
+        ]);
+        if (!opened.ok) {
+            return { kind: "refused", reason: opened.stderr || "gh could not open the pull request" };
+        }
+        const match = /(https:\/\/[^\s]*\/pull\/\d+)/.exec(opened.stdout);
+        return { kind: "opened", pullRequestUrl: match?.[1] };
+    }
+    finally {
+        await runCommand("git", ["-C", input.root, "worktree", "remove", "--force", worktree]);
+    }
+}

package/dist/markers.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Which of a promise's scope markers no longer name anything in this checkout.
+ *
+ * A rename is the ordinary way a promise stops being retrievable. Somebody
+ * moves `src/import/preview.ts` to `src/ingest/preview.ts`, the code keeps
+ * working, the check keeps passing, and the promise about it quietly stops
+ * overlapping any path an agent will ever name. Nothing on the server can see
+ * that: Balladeer holds no token for the repository and never reads a file, so
+ * the only place the fact exists is the working tree in front of the runner.
+ *
+ * So it is observed here, locally, and reported as attention rather than
+ * repaired. A marker is a piece of approved meaning; moving one is a semantic
+ * revision a named person makes, and a command that rewrote markers because a
+ * file moved would be editing what somebody agreed to on the strength of a
+ * `git mv`.
+ *
+ * What leaves this machine is nothing. The observation is printed where the
+ * person ran the command.
+ */
+/** How many missing markers one run reports, and how many it will even look at. */
+export declare const MARKER_OBSERVATION_LIMITS: {
+    /** Markers checked on disk in one run. Beyond this the run says it stopped counting. */
+    readonly maxChecked: 500;
+    /** Promises named in the printed row. The rest are counted, not listed. */
+    readonly maxNamed: 5;
+};
+/**
+ * A marker is a path when it names one.
+ *
+ * The grammar admits both `src/import/preview.ts` and `supplier-import-preview`.
+ * Only the first can be missing from a checkout; the second is a topic, and
+ * reporting it as a missing file would tell a person to go looking for
+ * something that was never a file.
+ */
+export declare function isPathShapedMarker(marker: string): boolean;
+export type MarkerObservation = Readonly<{
+    promiseId: string;
+    title: string;
+    /** The markers this promise names that are not in this checkout. */
+    missing: readonly string[];
+}>;
+export type MarkerObservationResult = Readonly<{
+    /** Promises with at least one missing path marker, in the order they were given. */
+    observations: readonly MarkerObservation[];
+    /** How many path-shaped markers were actually looked at. */
+    checked: number;
+    /** True when the run stopped at its ceiling and did not look at every marker. */
+    stoppedEarly: boolean;
+}>;
+export type MarkerSubject = Readonly<{
+    promiseId: string;
+    title: string;
+    surfaces?: readonly string[];
+    labels?: readonly string[];
+}>;
+/**
+ * Look for each promise's path markers in this working tree.
+ *
+ * Bounded twice over: it stops after `maxChecked` markers whatever remains, and
+ * it says that it stopped. A repository with a thousand promises must not turn
+ * `status` into a filesystem walk, and a run that silently examined the first
+ * few hundred would report "nothing missing" about a catalog it never read.
+ */
+export declare function observeMissingMarkers(repositoryRoot: string, subjects: readonly MarkerSubject[], limits?: Readonly<{
+    maxChecked: number;
+}>, exists?: (path: string) => boolean): MarkerObservationResult;
+/**
+ * The attention row a person reads, or nothing at all when every marker is
+ * still there.
+ *
+ * It names what to do and who does it: a marker is approved meaning, so the
+ * remedy is a revision somebody agrees to, never an edit this command makes.
+ */
+export declare function staleMarkerRow(result: MarkerObservationResult, limits?: Readonly<{
+    maxNamed: number;
+}>): string | undefined;

package/dist/markers.js

@@ -0,0 +1,125 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, join, normalize, sep } from "node:path";
+/**
+ * Which of a promise's scope markers no longer name anything in this checkout.
+ *
+ * A rename is the ordinary way a promise stops being retrievable. Somebody
+ * moves `src/import/preview.ts` to `src/ingest/preview.ts`, the code keeps
+ * working, the check keeps passing, and the promise about it quietly stops
+ * overlapping any path an agent will ever name. Nothing on the server can see
+ * that: Balladeer holds no token for the repository and never reads a file, so
+ * the only place the fact exists is the working tree in front of the runner.
+ *
+ * So it is observed here, locally, and reported as attention rather than
+ * repaired. A marker is a piece of approved meaning; moving one is a semantic
+ * revision a named person makes, and a command that rewrote markers because a
+ * file moved would be editing what somebody agreed to on the strength of a
+ * `git mv`.
+ *
+ * What leaves this machine is nothing. The observation is printed where the
+ * person ran the command.
+ */
+/** How many missing markers one run reports, and how many it will even look at. */
+export const MARKER_OBSERVATION_LIMITS = {
+    /** Markers checked on disk in one run. Beyond this the run says it stopped counting. */
+    maxChecked: 500,
+    /** Promises named in the printed row. The rest are counted, not listed. */
+    maxNamed: 5,
+};
+/**
+ * A marker is a path when it names one.
+ *
+ * The grammar admits both `src/import/preview.ts` and `supplier-import-preview`.
+ * Only the first can be missing from a checkout; the second is a topic, and
+ * reporting it as a missing file would tell a person to go looking for
+ * something that was never a file.
+ */
+export function isPathShapedMarker(marker) {
+    const trimmed = marker.trim();
+    if (trimmed === "")
+        return false;
+    if (trimmed.includes("/"))
+        return true;
+    return /^[^/]+\.[A-Za-z0-9]{1,8}$/.test(trimmed);
+}
+/**
+ * A marker refused rather than resolved.
+ *
+ * A marker that escapes the repository root, or that arrives absolute, is not a
+ * marker this checkout can answer for. It is skipped rather than reported
+ * missing: telling a person a path is gone because the command would not look
+ * outside their repository is a false alarm about their catalog.
+ */
+function resolveInside(root, marker) {
+    const cleaned = marker.trim().replaceAll("\\", "/");
+    if (cleaned === "" || isAbsolute(cleaned))
+        return undefined;
+    const full = normalize(join(root, cleaned));
+    const bounded = root.endsWith(sep) ? root : `${root}${sep}`;
+    return full === root || full.startsWith(bounded) ? full : undefined;
+}
+/**
+ * Look for each promise's path markers in this working tree.
+ *
+ * Bounded twice over: it stops after `maxChecked` markers whatever remains, and
+ * it says that it stopped. A repository with a thousand promises must not turn
+ * `status` into a filesystem walk, and a run that silently examined the first
+ * few hundred would report "nothing missing" about a catalog it never read.
+ */
+export function observeMissingMarkers(repositoryRoot, subjects, limits = MARKER_OBSERVATION_LIMITS, exists = existsSync) {
+    const root = normalize(repositoryRoot);
+    const observations = [];
+    let checked = 0;
+    let stoppedEarly = false;
+    for (const subject of subjects) {
+        const missing = [];
+        for (const marker of [...(subject.surfaces ?? []), ...(subject.labels ?? [])]) {
+            if (!isPathShapedMarker(marker))
+                continue;
+            if (checked >= limits.maxChecked) {
+                stoppedEarly = true;
+                break;
+            }
+            checked += 1;
+            const resolved = resolveInside(root, marker);
+            if (resolved === undefined)
+                continue;
+            if (!exists(resolved))
+                missing.push(marker.trim());
+        }
+        if (missing.length > 0) {
+            observations.push({ promiseId: subject.promiseId, title: subject.title, missing });
+        }
+        if (stoppedEarly)
+            break;
+    }
+    return { observations, checked, stoppedEarly };
+}
+/**
+ * The attention row a person reads, or nothing at all when every marker is
+ * still there.
+ *
+ * It names what to do and who does it: a marker is approved meaning, so the
+ * remedy is a revision somebody agrees to, never an edit this command makes.
+ */
+export function staleMarkerRow(result, limits = MARKER_OBSERVATION_LIMITS) {
+    const { observations } = result;
+    if (observations.length === 0)
+        return undefined;
+    const named = observations.slice(0, Math.max(0, limits.maxNamed));
+    const lines = named.map((observation) => `      ${observation.promiseId}: ${observation.missing.join(", ")} (${observation.title})`);
+    const rest = observations.length - named.length;
+    const head = observations.length === 1
+        ? "  Attention: 1 promise names a path that is not in this checkout, so it will not be found by the paths a change touches."
+        : `  Attention: ${observations.length} promises name a path that is not in this checkout, so they will not be found by the paths a change touches.`;
+    const tail = [
+        ...(rest > 0 ? [`      and ${rest} more.`] : []),
+        ...(result.stoppedEarly
+            ? [
+                `      This run looked at ${result.checked} markers and stopped there, so there may be more.`,
+            ]
+            : []),
+        "      A marker is part of what somebody agreed to. Propose a revision and let its owner decide; nothing here changed it.",
+    ];
+    return [head, ...lines, ...tail].join("\n");
+}