@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/trust/verify-cli.js

@@ -0,0 +1,63 @@
+/**
+ * `chant workspace verify [--base <rev>] [--head <rev>] [--require attested | attested-runs] [--json]`
+ * (#2547): check a change against the trust policy at its base. See ./verify.ts.
+ *
+ * Exit 0 when the change passes, 1 when it does not or cannot be checked.
+ */
+import { formatError, formatSuccess } from "../../cli/format.js";
+import { gitRoot } from "../record-source.js";
+import { activeAttestors } from "./attestor.js";
+import { verifyChange } from "./verify.js";
+const USAGE = "chant workspace verify [--base <rev>] [--head <rev>] [--require attested | attested-runs] [--json]";
+export async function runWorkspaceVerify(ctx) {
+    const { args } = ctx;
+    if (args.require !== undefined && args.require !== "attested" && args.require !== "attested-runs") {
+        console.error(formatError({ message: `--require takes attested or attested-runs, not ${JSON.stringify(args.require)}`, hint: USAGE }));
+        return 1;
+    }
+    const repo = gitRoot(process.cwd());
+    if (!repo) {
+        console.error(formatError({ message: "chant workspace verify checks git commits, and this directory is not in a git repository", hint: USAGE }));
+        return 1;
+    }
+    const report = verifyChange({
+        repo,
+        base: args.base,
+        head: args.head,
+        require: args.require === "attested" || args.require === "attested-runs" ? args.require : undefined,
+        attestors: await activeAttestors(),
+    });
+    if (args.json)
+        console.log(JSON.stringify(report, null, 2));
+    else
+        printReport(report);
+    return report.ok ? 0 : 1;
+}
+function printReport(r) {
+    const lines = [];
+    if (r.base)
+        lines.push(`base ${r.base.slice(0, 8)} (${r.baseFrom})${r.head ? `, head ${r.head.slice(0, 8)}` : ""}`);
+    if (r.policy.active) {
+        lines.push(`policy at base: ${r.policy.principals.length} signers in ${r.policy.signersPath}; policy writers: ${r.policy.writers.join(", ") || "none"}`);
+        for (const e of r.policy.excluded)
+            lines.push(`  ${r.policy.signersPath}:${e.line} not used: ${e.reason}`);
+    }
+    for (const c of r.commits) {
+        const who = c.principal ? ` by ${c.principal}` : "";
+        const note = c.skipped ? ` (${c.skipped})` : c.level === "attested" ? "" : ` (${c.reason})`;
+        lines.push(`  ${c.commit.slice(0, 8)}  ${c.level}${who}  ${c.subject}${note}`);
+    }
+    for (const c of r.runs.commits)
+        lines.push(`  ${c.commit.slice(0, 8)}  agent run ${c.runs.join(", ") || c.run}: ${c.attested ? "attested" : "not attested"}, ${c.reason}`);
+    for (const w of r.protectedWrites)
+        lines.push(`  protected write ${w.commit.slice(0, 8)} ${w.paths.join(", ")}: ${w.allowed ? "allowed" : "refused"}, ${w.reason}`);
+    if (r.rotation && "to" in r.rotation)
+        lines.push(`  signer set: version ${r.rotation.from} to ${r.rotation.to}, signed by ${r.rotation.signedBy.join(", ")}`);
+    for (const n of r.notes)
+        lines.push(n);
+    console.log(lines.join("\n"));
+    if (r.ok)
+        console.log(formatSuccess(`verified ${r.commits.length} commits against the policy at base`));
+    else
+        console.error(formatError({ message: `verification failed:\n${r.failures.map((f) => `  ${f}`).join("\n")}`, hint: USAGE }));
+}

package/dist/workspace/trust/verify.js

@@ -0,0 +1,192 @@
+/**
+ * Verify a change against the policy at its base (#2524 D5, Threat model).
+ *
+ * This is what CI runs on a protected branch: every commit in `base..head` is
+ * asked of the attestors with the policy read at base, so nothing the change
+ * does to its own copy of the policy counts. A change that edits the policy
+ * (the signers file or `.chant/trust.json`) is a protected write: every commit
+ * that touches those files must be attested by a signer the base policy
+ * trusts, and by an admin when the base policy grants the admin role.
+ *
+ * Attestation is opt-in (#2525 rule 6). Without a signers file at base the
+ * check passes and says so, unless `--require attested` asks for more.
+ *
+ * Agent runs (#3192): a commit an agent run made, by its `Chant-Run` trailer
+ * or its run's end, is attested by a run statement that a runner or steward
+ * key at base signed and that names the commit. Such a commit counts as
+ * `attested` with the attestor `agent-run`, so `--require attested` tells a
+ * person's signed commit from a run's attested one by the attestor.
+ * `--require attested-runs` asks only that every commit a run made be
+ * covered, and needs runner keys at base but no signers file. Without
+ * `--require`, `runs` reports and nothing fails (studio-035 d).
+ */
+import { execFileSync } from "node:child_process";
+import { policyAtBase, commitProvenance, resolveBase } from "./provenance.js";
+import { policyWriters, protectedPaths } from "./policy.js";
+import { fileAt, nextVersion, rotationPath, signerHistory } from "./rotation.js";
+import { changeRuns } from "./run-commits.js";
+function git(repo, args) {
+    return execFileSync("git", args, { cwd: repo, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+}
+/**
+ * Commits in `range` that change any of `paths`, each with the paths it
+ * changes. Merges count only for what they change beyond every parent.
+ */
+export function commitsTouching(repo, range, paths) {
+    const out = new Map();
+    const log = git(repo, ["--literal-pathspecs", "log", "-c", "--name-only", "--no-renames", "--format=%x00%H", range, "--", ...paths]);
+    const wanted = new Set(paths);
+    let commit = "";
+    for (const line of log.split("\n")) {
+        if (line.startsWith("\0"))
+            commit = line.slice(1).trim();
+        else if (line && wanted.has(line))
+            out.set(commit, [...(out.get(commit) ?? []), line]);
+    }
+    return out;
+}
+/** Whether a merge commit changes nothing beyond what its parents bring. */
+function mergeWithoutOwnChanges(repo, commit, parents) {
+    if (parents < 2)
+        return false;
+    return git(repo, ["diff-tree", "-c", "--name-only", "--no-commit-id", "-r", commit]).trim() === "";
+}
+export function verifyChange(opts) {
+    const { repo } = opts;
+    const base = resolveBase(repo, opts.base);
+    const policy = policyAtBase(repo, base);
+    const report = {
+        base: base.commit,
+        baseFrom: base.from,
+        head: null,
+        policy: {
+            active: policy.active,
+            signersPath: policy.signersPath,
+            principals: [...new Set(policy.signers.map((s) => s.principal))].sort(),
+            excluded: policy.excluded,
+            writers: [...policyWriters(policy)].sort(),
+            problems: policy.problems,
+        },
+        require: opts.require ?? null,
+        commits: [],
+        runs: { ledger: null, runners: [], commits: [] },
+        protectedPaths: protectedPaths(policy),
+        protectedChanged: [],
+        protectedWrites: [],
+        rotation: null,
+        notes: [],
+        failures: [],
+        ok: false,
+    };
+    const headRev = opts.head ?? "HEAD";
+    let head;
+    try {
+        head = headRev.startsWith("-") ? undefined : git(repo, ["rev-parse", "--verify", "--quiet", `${headRev}^{commit}`]).trim() || undefined;
+    }
+    catch {
+        head = undefined;
+    }
+    if (!base.commit)
+        report.failures.push(base.problem ?? "no base revision");
+    if (!head)
+        report.failures.push(`--head ${headRev} names no commit in this repository`);
+    if (!base.commit || !head)
+        return report;
+    report.head = head;
+    if (policy.problems.length > 0) {
+        report.failures.push(...policy.problems.map((p) => `the policy at base cannot be read, so nothing verifies: ${p}`));
+        return report;
+    }
+    // Every commit in the change, oldest first, with its parents.
+    const listing = git(repo, ["rev-list", "--reverse", "--parents", `${base.commit}..${head}`]).split("\n").filter(Boolean);
+    const parentsOf = new Map(listing.map((l) => { const [c, ...p] = l.split(" "); return [c, p.length]; }));
+    report.runs = changeRuns(repo, [...parentsOf.keys()], policy.runners);
+    if (opts.require === "attested-runs") {
+        if (policy.runners.length === 0 && report.runs.commits.length > 0) {
+            report.notes.push(`.chant/trust.json at base lists no runner keys, so no run statement can verify`);
+        }
+        for (const r of report.runs.commits) {
+            if (r.attested || r.runs.length === 0 || mergeWithoutOwnChanges(repo, r.commit, parentsOf.get(r.commit) ?? 0))
+                continue;
+            report.failures.push(`${r.commit.slice(0, 8)} was made by agent run ${r.runs.join(", ")}, and --require attested-runs was given: ${r.reason}`);
+        }
+    }
+    const mergeBase = git(repo, ["merge-base", base.commit, head]).trim();
+    const changedPaths = git(repo, ["--literal-pathspecs", "diff", "--name-only", "--no-renames", mergeBase, head, "--", ...report.protectedPaths])
+        .split("\n")
+        .filter(Boolean);
+    report.protectedChanged = changedPaths;
+    if (!policy.active) {
+        report.notes.push(`no signers file (${policy.signersPath}) at base ${base.commit.slice(0, 8)}: attestation is off and nothing is verified`);
+        if (changedPaths.includes(policy.signersPath)) {
+            report.notes.push(`this change adds ${policy.signersPath}; it applies to changes made after it is merged, never to this one`);
+        }
+        if (opts.require && opts.require !== "attested-runs")
+            report.failures.push(`--require ${opts.require} was given, and there is no signers file at base to attest anything`);
+        report.ok = report.failures.length === 0;
+        return report;
+    }
+    // Every commit in the change, judged by the policy at base.
+    const runCover = new Map(report.runs.commits.filter((r) => r.attested).map((r) => [r.commit, r]));
+    const verdicts = new Map();
+    for (const line of listing) {
+        const [commit, ...parents] = line.split(" ");
+        const subject = git(repo, ["log", "-1", "--format=%s", commit]).trim();
+        let p = commitProvenance(repo, policy, commit, opts.attestors);
+        const cover = runCover.get(commit);
+        // A commit no signer attests, made by a run a runner key at base vouches for (#3192).
+        if (p.level !== "attested" && cover)
+            p = { level: "attested", commit, attestor: "agent-run", principal: cover.signer, reason: cover.reason };
+        const v = { ...p, commit, subject };
+        if (p.level !== "attested" && mergeWithoutOwnChanges(repo, commit, parents.length)) {
+            v.skipped = "a merge with no changes of its own; the commits it brings are checked instead";
+        }
+        verdicts.set(commit, v);
+        report.commits.push(v);
+    }
+    // Protected writes: every commit that touches the policy needs a writer's signature.
+    if (changedPaths.length > 0) {
+        const writers = policyWriters(policy);
+        const touching = commitsTouching(repo, `${base.commit}..${head}`, report.protectedPaths);
+        if (touching.size === 0) {
+            report.failures.push(`the policy files ${changedPaths.join(", ")} differ from base, and no commit in the change accounts for it`);
+        }
+        for (const [commit, paths] of touching) {
+            const v = verdicts.get(commit) ?? { ...commitProvenance(repo, policy, commit, opts.attestors), commit, subject: "" };
+            const allowed = v.level === "attested" && v.principal !== undefined && writers.has(v.principal);
+            const who = policy.roles.admin?.length ? "an admin the policy at base names" : "a signer the policy at base lists";
+            const reason = allowed
+                ? `signed by ${v.principal}, ${who.replace(/^an? /, "")}`
+                : v.level === "attested"
+                    ? `signed by ${v.principal}, who is not ${who}`
+                    : `${paths.join(", ")} is protected and needs a signature by ${who}: ${v.reason}`;
+            report.protectedWrites.push({ commit, paths, level: v.level, ...(v.principal ? { principal: v.principal } : {}), allowed, reason });
+            if (!allowed)
+                report.failures.push(`${commit.slice(0, 8)} changes ${paths.join(", ")}: ${reason}`);
+        }
+    }
+    // A new signer set must be signed by a threshold of the set at base (#2553).
+    const rotation = rotationPath(policy.signersPath);
+    if (changedPaths.includes(policy.signersPath) || changedPaths.includes(rotation)) {
+        const next = { signers: fileAt(repo, head, policy.signersPath), rotation: fileAt(repo, head, rotation) };
+        const latest = signerHistory(repo, base.commit, policy.signersPath).versions.at(-1);
+        if (next.signers !== undefined && latest && latest.version > 0) {
+            const v = nextVersion(latest, next, null);
+            if ("code" in v) {
+                report.rotation = { from: latest.version, code: v.code, reason: v.reason };
+                report.failures.push(`the signer set at head is not a valid rotation of the set at base (${v.code}): ${v.reason}`);
+            }
+            else if (v !== latest)
+                report.rotation = { from: latest.version, to: v.version, signedBy: v.signedBy };
+        }
+    }
+    if (opts.require && opts.require !== "attested-runs") {
+        for (const v of report.commits) {
+            if (v.skipped || v.level === opts.require)
+                continue;
+            report.failures.push(`${v.commit.slice(0, 8)} is ${v.level}, and --require ${opts.require} was given: ${v.reason}`);
+        }
+    }
+    report.ok = report.failures.length === 0;
+    return report;
+}

package/dist/workspace/which-chant.js

@@ -0,0 +1,141 @@
+/**
+ * Where a workspace read starts, and which chant does it (#2536; #2524 D15,
+ * ws-016, ws-021).
+ *
+ * {@link locateWorkspace} finds the declaration from a directory, in the
+ * working tree or in one commit's git objects (`--at <rev>`), and gives the
+ * tree every read-contract command reads from.
+ *
+ * Which chant reads the declaration: the root's. The root names its chant by
+ * pinning `@intentius/chant` in the declaration's `pins`. When it pins one,
+ * that version reads the declaration, and any other chant refuses with
+ * `root-chant-required` (`parseDeclaration`'s `rootChant` option). The CLI
+ * first hands the whole command to the pinned chant when the root has it
+ * installed ({@link handToRootChant}), so a user sees the refusal only when
+ * it isn't. When the root pins no chant, the reader's own chant reads the
+ * declaration if it meets `minReader`, and refuses with `reader-too-old`
+ * otherwise. Members are always read by their own toolchains.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { findWorkspaceRoot } from "../project-root.js";
+import { CHANT_PACKAGE, DECLARATION_FILES, findDeclarationDir, pinnedChant, readerVersion, WorkspaceReadError } from "./declaration.js";
+import { parseJsonText } from "./jsonc.js";
+import { findInstalledPackage } from "./kinds.js";
+import { gitTop, gitTree, resolveCommit, workingTree } from "./tree.js";
+const posix = (p) => p.split("\\").join("/");
+/**
+ * Find the workspace whose declaration is nearest above `cwd`, in the working
+ * tree or at revision `at`. Throws a {@link WorkspaceReadError}:
+ * `declaration-missing`, or for `--at`, `not-a-git-repository` and
+ * `revision-unknown`.
+ */
+export function locateWorkspace(cwd, at) {
+    const top = gitTop(cwd);
+    if (at !== undefined) {
+        if (!top)
+            throw new WorkspaceReadError("not-a-git-repository", "--at reads git objects, and this directory is not in a git repository");
+        const commit = resolveCommit(top, at);
+        if (!commit)
+            throw new WorkspaceReadError("revision-unknown", `--at ${at} names no commit in this repository`);
+        const whole = gitTree(top, commit);
+        const start = posix(relative(top, realpathSync(resolve(cwd))));
+        const found = findDeclarationDir(whole, start.startsWith("..") ? "" : start);
+        if (found === undefined) {
+            throw new WorkspaceReadError("declaration-missing", `no chant.workspace.json or .jsonc between ${start || "."} and the git root at ${commit.slice(0, 8)}`);
+        }
+        return {
+            tree: found === "" ? whole : gitTree(top, commit, found),
+            root: found === "" ? "." : found,
+            rootOnDisk: join(top, ...found.split("/")),
+            at: commit,
+            top,
+        };
+    }
+    const found = findWorkspaceRoot(cwd);
+    if (!found) {
+        throw new WorkspaceReadError("declaration-missing", top
+            ? "no chant.workspace.json or .jsonc between this directory and the git root; chant workspace init proposes one"
+            : "no chant.workspace.json or .jsonc in this directory; chant workspace init proposes one");
+    }
+    // git reports the top with symlinks resolved (/private/var on macOS), so compare like with like.
+    const rel = top ? posix(relative(top, realpathSync(found.dir))) : found.dir;
+    return { tree: workingTree(found.dir), root: rel === "" ? "." : rel, rootOnDisk: found.dir, at: null, top };
+}
+/**
+ * The `bin/chant` of `@intentius/chant` at `version`, installed where the
+ * workspace root resolves packages. Undefined when it isn't installed there,
+ * or is installed at another version.
+ */
+export function rootChantBin(rootOnDisk, version) {
+    const dir = findInstalledPackage(CHANT_PACKAGE, rootOnDisk);
+    if (!dir)
+        return undefined;
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (pkg.version !== version)
+        return undefined;
+    const rel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.chant;
+    if (typeof rel !== "string")
+        return undefined;
+    const bin = join(dir, rel);
+    return existsSync(bin) ? bin : undefined;
+}
+/** Set in the environment of a command handed to the root's chant, so it is handed on once at most. */
+export const HANDED_TO_ROOT_ENV = "CHANT_WORKSPACE_ROOT_CHANT";
+/** The version the declaration at `located` pins for `@intentius/chant`, or undefined. Never throws. */
+export function declaredChantPin(located) {
+    const file = DECLARATION_FILES.find((f) => located.tree.stat(f) === "file");
+    if (!file)
+        return undefined;
+    let text;
+    try {
+        text = located.tree.read(file);
+    }
+    catch {
+        return undefined;
+    }
+    const parsed = parseJsonText(text, { jsonc: file.endsWith(".jsonc") });
+    if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object" || Array.isArray(parsed.value))
+        return undefined;
+    return pinnedChant(parsed.value)?.version;
+}
+/**
+ * Hand a read-contract command to the root's chant (ws-021). When the
+ * declaration above `cwd` (at `at`, for `--at`) pins a chant other than this
+ * one, and the root has that chant installed, run the same command line
+ * under it and return its exit code. Otherwise return undefined, and this
+ * chant runs the command: it reads the declaration itself, or refuses with
+ * `root-chant-required` when the pinned chant isn't installed.
+ */
+export async function handToRootChant(cwd, at, argv = process.argv.slice(2)) {
+    if (process.env[HANDED_TO_ROOT_ENV])
+        return undefined;
+    let located;
+    try {
+        located = locateWorkspace(cwd, at);
+    }
+    catch {
+        return undefined;
+    }
+    const pinned = declaredChantPin(located);
+    if (pinned === undefined || pinned === readerVersion())
+        return undefined;
+    const bin = rootChantBin(located.rootOnDisk, pinned);
+    if (!bin)
+        return undefined;
+    return new Promise((done) => {
+        const child = spawn(bin, argv, { stdio: "inherit", env: { ...process.env, [HANDED_TO_ROOT_ENV]: pinned } });
+        child.on("error", (e) => {
+            process.stderr.write(`could not start the root's chant ${pinned} at ${bin}: ${e.message}\n`);
+            done(1);
+        });
+        child.on("close", (code) => done(code ?? 1));
+    });
+}

package/dist/workspace/wip-cli.js

@@ -0,0 +1,95 @@
+/**
+ * `chant workspace wip` (#3172, ws-085): work in progress under
+ * `refs/chant/wip/<branch>`, and its replication.
+ *
+ *   wip [--branch <branch>] [--json]              every branch's snapshots, and where replication stands
+ *   wip save [--label <text>] [--by <principal>]  snapshot the working tree, then push if the policy says so
+ *   wip restore [<snapshot>] [--by <principal>]   put the working tree back as a snapshot holds it
+ *   wip push                                      push what the policy names, for the host's schedule
+ *   wip fetch                                     on a replacement box, bring back what was replicated
+ *
+ * The read prints `wip.schema.json` with `--json`; every write prints
+ * `wip-write.schema.json`, with or without `--json`.
+ */
+import { formatError } from "../cli/format.js";
+import { readerVersion } from "./declaration.js";
+import { wipFetch, wipPush, wipRestore, wipSave, workspaceWip, WIP_CONTRACT_VERSION, WIP_WRITE_SCHEMA_ID } from "./wip.js";
+import { AGENT_ENV } from "./write-scope.js";
+const USAGE = "chant workspace wip [--branch <branch>] [--json] | wip save [--label <text>] [--by <principal>] | wip restore [<snapshot>] [--by <principal>] | wip push | wip fetch";
+const VERBS = ["save", "restore", "push", "fetch"];
+export async function runWorkspaceWip(ctx) {
+    const { args } = ctx;
+    const cwd = process.cwd();
+    // workspace wip [<verb> [<snapshot>]]
+    const [, verb, ...rest] = args.positionals ?? [];
+    if (verb === undefined) {
+        if (rest.length > 0 || args.label !== undefined) {
+            console.error(formatError({ message: "chant workspace wip lists work in progress; save, restore, push and fetch write it", hint: USAGE }));
+            return 1;
+        }
+        const doc = workspaceWip({ cwd, branch: args.branch });
+        if (args.json || "error" in doc) {
+            console.log(JSON.stringify(doc, null, 2));
+            return "error" in doc ? 1 : 0;
+        }
+        console.log(formatWip(doc));
+        return 0;
+    }
+    const print = (doc) => {
+        console.log(JSON.stringify(doc, null, 2));
+        return "error" in doc ? 1 : 0;
+    };
+    const usage = (action, message) => print({ $schema: WIP_WRITE_SCHEMA_ID, contract: WIP_CONTRACT_VERSION, chant: readerVersion(), action, error: { code: "write-usage-invalid", message } });
+    if (!VERBS.includes(verb))
+        return usage(null, `chant workspace wip takes save, restore, push or fetch, not ${verb}: ${USAGE}`);
+    const action = verb;
+    const agent = process.env[AGENT_ENV] || undefined;
+    if (args.branch !== undefined)
+        return usage(action, `wip ${action} works on the branch checked out; --branch is for listing`);
+    switch (action) {
+        case "save":
+            if (rest.length > 0)
+                return usage(action, `wip save takes no positional argument, and was given ${rest.join(" ")}; name the snapshot with --label`);
+            return print(wipSave({ cwd, label: args.label, by: args.by, agent }));
+        case "restore":
+            if (rest.length > 1)
+                return usage(action, `wip restore takes at most one snapshot, and was given ${rest.join(" ")}`);
+            if (args.label !== undefined)
+                return usage(action, "wip restore takes the snapshot's commit, not --label");
+            return print(wipRestore({ cwd, snapshot: rest[0], by: args.by, agent }));
+        case "push":
+        case "fetch":
+            if (rest.length > 0 || args.label !== undefined || args.by !== undefined)
+                return usage(action, `wip ${action} takes no arguments: it does what the box's replicate policy says`);
+            return print(action === "push" ? wipPush({ cwd }) : wipFetch({ cwd }));
+    }
+}
+/** The text `chant workspace wip` prints without `--json`. */
+export function formatWip(doc) {
+    const lines = [];
+    if (doc.branches.length === 0)
+        lines.push("No work in progress is kept under refs/chant/wip/.");
+    for (const b of doc.branches) {
+        const here = b.branch === doc.checkout.branch ? " (checked out)" : "";
+        lines.push(`${b.branch}${here}: ${b.snapshots.length} snapshot${b.snapshots.length === 1 ? "" : "s"}`);
+        for (const s of b.snapshots.slice(0, 10)) {
+            const what = [s.kind === "pre-restore" ? "before a restore" : null, s.label, s.by ? `by ${s.by}` : null].filter(Boolean).join(", ");
+            lines.push(`  ${s.commit.slice(0, 12)}  ${s.at}  on ${s.head.slice(0, 12)}${what ? `  ${what}` : ""}`);
+        }
+        if (b.snapshots.length > 10)
+            lines.push(`  ... and ${b.snapshots.length - 10} older`);
+    }
+    const r = doc.replication;
+    if (r === null) {
+        lines.push("", "No box declares replicate, so work in progress stays on this disk.");
+    }
+    else {
+        const behind = r.refs.filter((x) => !x.replicated);
+        lines.push("", `Replicated to ${r.policy.remote} (${r.policy.box}'s box: ${r.policy.refs.join(", ")}; pushes on ${r.policy.on.join(" and ") || "wip push only"}${r.policy.every ? `, and every ${r.policy.every} by the host` : ""})${r.remoteConfigured ? "" : `; this checkout has no remote named ${r.policy.remote}`}`);
+        if (behind.length === 0)
+            lines.push(`  all ${r.refs.length} refs are on the remote`);
+        for (const x of behind)
+            lines.push(`  ${x.ref}: not on the remote${x.ahead > 0 ? `, ${x.ahead} commit${x.ahead === 1 ? "" : "s"} ahead` : ""}`);
+    }
+    return lines.join("\n");
+}