@cspeach/cli 1.1.14 → 1.1.15

package/dist/commands/team.js

@@ -0,0 +1,1166 @@
+/**
+ * `cspeach team …` — a team project from the terminal
+ * (spec: docs/superpowers/specs/2026-09-18-project-register-folder-mode.md §6).
+ *
+ *   init <folder>   lead: pull the baseline from SAP, write the team project folder
+ *   join <folder>   everyone: start recording against a team project
+ *   lane …          lead: who owns which packages
+ *   refresh …       anyone connected: measure a lane, packages or everything with ATC
+ *   status [folder] anyone: the register as text
+ *   outbox          what this laptop has recorded, and where
+ *   rule …          lead: settle a disagreement
+ *   leave           stop recording
+ *
+ * Every path written here is one a person typed. Nothing is written to a
+ * network location on CSPeach's own initiative, and none of this is reachable
+ * from a model tool.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { activeOf, buildRegister, narrowedLanes, objectKey, provenOf, } from '@cspeach/register-core';
+import { LOCAL_PACKAGE, listCustomPackages, pullBaseline, BaselineError } from '../register/baseline.js';
+import { BASELINE_FILE, TEAM_FILE, RegisterError, activeProject, collectRecords, defaultOutboxDir, loadState, projectIdFor, readBaseline, readLanes, readProjectFile, saveState, sha256, VARIANT_NAME, writeLanes, writeProjectVariant, writerIdFor, } from '../register/store.js';
+import { measure, noVariantYetMessage, scopeLabel, scopeObjects, variantMismatchMessage, } from '../register/measure.js';
+import { measureFromFile, shown, upToFive } from '../register/atc-file.js';
+import { writeRecord } from '../register/records.js';
+const CLASSIFICATIONS = ['keep', 'fix', 'retire', 'redesign'];
+const TYPES = ['clean-core', 'upgrade', 'build'];
+/**
+ * Who this laptop is, for the team project it has joined.
+ *
+ * The name a person gave with `team init --lead` wins over the one the machine
+ * offers, and only for that team project. Without one, nothing changes: the
+ * name comes from `deps.identity()` exactly as it always has.
+ *
+ * It matters everywhere, not only in the team project file: `requireLead`
+ * compares this with the lead's name, a ruling only counts when it comes from
+ * the lead, and every record says who wrote it.
+ */
+const whoAmI = (deps) => activeProject()?.name ?? deps.identity().name;
+/**
+ * Names that are a machine's, not a person's. A team project whose lead is
+ * "Admin" says nothing about who leads it, and the writer id, the rulings and
+ * every record carry that name from then on.
+ */
+const MACHINE_NAMES = new Set(['admin', 'administrator', 'user', 'root']);
+function looksLikeAMachine(name, deps) {
+    const said = name.trim().toLowerCase();
+    if (!said)
+        return true;
+    if (MACHINE_NAMES.has(said))
+        return true;
+    const machine = (deps.machine?.() ?? os.hostname()).trim().toLowerCase();
+    return said === machine;
+}
+/**
+ * The loose parser the older verbs share. `flagOnly` names the options that
+ * take no value, so `--no-measure <folder>` cannot swallow the folder name —
+ * and a verb that passes it also gets `--name=Wave`, the spelling `refresh`
+ * has always taken. The verbs that pass nothing read exactly as before.
+ */
+function flags(args, flagOnly = []) {
+    const positional = [];
+    const opts = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!a.startsWith('--')) {
+            positional.push(a);
+            continue;
+        }
+        const equals = flagOnly.length ? a.indexOf('=') : -1;
+        if (equals > 2) {
+            opts[a.slice(2, equals)] = a.slice(equals + 1) || 'true';
+            continue;
+        }
+        const name = a.slice(2);
+        if (flagOnly.includes(name)) {
+            opts[name] = 'true';
+            continue;
+        }
+        opts[name] = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : 'true';
+    }
+    return { positional, opts };
+}
+const list = (v) => (v ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+/** "1 object", "3 objects" — every count this command prints reads as a sentence. */
+const plural = (count, one, many) => `${count} ${count === 1 ? one : many}`;
+/** `ZFI_*` style match, used only to expand --packages patterns against the real package list. */
+function matches(pattern, value) {
+    const re = new RegExp(`^${pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`, 'i');
+    return re.test(value);
+}
+export async function runTeamCommand(args, deps) {
+    const [sub, ...rest] = args;
+    try {
+        switch (sub) {
+            case 'init': return await init(rest, deps);
+            case 'join': return join(rest, deps);
+            case 'lane': return lane(rest, deps);
+            case 'refresh': return await refresh(rest, deps);
+            case 'status': return status(rest, deps);
+            case 'outbox': return outbox(rest, deps);
+            case 'rule': return rule(rest, deps);
+            case 'leave': return leave(deps);
+            default:
+                deps.print('Usage: cspeach team init|join|lane|refresh|status|outbox|rule|leave   (cspeach --help for details)');
+                return sub ? 1 : 0;
+        }
+    }
+    catch (e) {
+        if (e instanceof RegisterError || e instanceof BaselineError) {
+            deps.print(`✗ ${e.message}`);
+            return 1;
+        }
+        throw e;
+    }
+}
+function requireLead(project, deps) {
+    const me = whoAmI(deps);
+    if (me.trim().toLowerCase() !== project.lead.name.trim().toLowerCase()) {
+        throw new RegisterError(`Only the team project lead (${project.lead.name}) changes this. You are ${me}.`);
+    }
+}
+function joinedOrThrow() {
+    const joined = activeProject();
+    if (!joined)
+        throw new RegisterError('This laptop has not joined a team project. Run: cspeach team join <folder>');
+    return joined;
+}
+// ── init ────────────────────────────────────────────────────────────────────
+const INIT_USAGE = 'Usage: cspeach team init <folder> --name "<name>" [--lead "<your name>"] [--type clean-core|upgrade|build] '
+    + '[--packages ZFI_*,ZSD_*] [--include-local] [--atc-variant <NAME>] [--no-measure]';
+/** Everything `init` understands. Anything else is a typo, and a typo is refused, never ignored. */
+const INIT_OPTIONS = ['name', 'lead', 'type', 'packages', 'include-local', 'sap-alias', 'atc-variant', 'no-measure'];
+/** The two that take no value, so neither can eat the folder name. */
+const INIT_FLAGS = ['include-local', 'no-measure'];
+/** Typed on `init` out of muscle memory: they choose what to MEASURE, which is another verb. */
+const REFRESH_ONLY = ['all', 'lane', 'force-variant', 'chunk', 'max-minutes', 'no-one-by-one', 'from-file', 'absent-means-clean'];
+/**
+ * What `init` says about an option it does not know.
+ *
+ * A guess must never mean the opposite of what was typed: `--measure` answered
+ * with "did you mean --no-measure?" sends a person the other way. So the edit
+ * distance allowed grows with the length of the word, `no-measure` is offered
+ * only to a word that already starts with "no", and the three options people
+ * really reach for get an answer of their own.
+ */
+function unknownInitOption(name) {
+    const said = `Unknown option --${name}.`;
+    if (name === 'measure')
+        return `${said} init measures by default when it can. Use --no-measure to skip it.`;
+    if (name === 'variant')
+        return `${said} Did you mean --atc-variant?`;
+    if (REFRESH_ONLY.includes(name)) {
+        return `${said} That option belongs to cspeach team refresh, which measures. init only creates the team project.`;
+    }
+    const guess = near(name, INIT_OPTIONS, Math.min(3, Math.floor(name.length / 4) + 1));
+    if (!guess || (guess === 'no-measure' && !name.toLowerCase().startsWith('no')))
+        return said;
+    return `${said} Did you mean --${guess}?`;
+}
+async function init(args, deps) {
+    const { positional, opts } = flags(args, INIT_FLAGS);
+    // `--no-measur` must not read as "measure anyway": a person who meant to skip
+    // the first measurement would be told nothing and would wait for a check run.
+    for (const name of Object.keys(opts)) {
+        if (INIT_OPTIONS.includes(name))
+            continue;
+        throw new RegisterError(`${unknownInitOption(name)}\n${INIT_USAGE}`);
+    }
+    const folder = positional[0];
+    if (!folder)
+        throw new RegisterError(INIT_USAGE);
+    const dir = path.resolve(folder);
+    if (fs.existsSync(path.join(dir, TEAM_FILE)))
+        throw new RegisterError(`${dir} already holds a team project. Pick an empty folder.`);
+    const name = opts.name ?? path.basename(dir);
+    // F4: the lead's own name, said once, or the one the machine offers. `true`
+    // is what the parser gives `--lead` with nothing after it.
+    const given = opts.lead && opts.lead !== 'true' ? opts.lead.trim().slice(0, 80) : '';
+    if (opts.lead !== undefined && !given)
+        throw new RegisterError(`--lead needs a name, for example: --lead "David Carter"\n${INIT_USAGE}`);
+    const lead = given || deps.identity().name;
+    const type = (opts.type ?? 'clean-core');
+    if (!TYPES.includes(type))
+        throw new RegisterError(`--type must be one of: ${TYPES.join(', ')}`);
+    // One variant per team project (D6), named here or never. A name SAP could
+    // not accept is refused before a folder exists, not after it is written in.
+    const atcVariant = opts['atc-variant'] && opts['atc-variant'] !== 'true' ? opts['atc-variant'].trim().toUpperCase() : '';
+    if (atcVariant && !VARIANT_NAME.test(atcVariant))
+        throw new RegisterError(`"${opts['atc-variant'].trim()}" is not an ATC check variant name.`);
+    if (!deps.connect)
+        throw new RegisterError('init needs a SAP connection to pull the object list.');
+    const { sql, system, atc } = await deps.connect(opts['sap-alias']);
+    deps.print('Reading the package list from SAP…');
+    const all = await listCustomPackages(sql);
+    const patterns = list(opts.packages);
+    let chosen = all.filter((p) => patterns.some((pat) => matches(pat, p.package)));
+    if (!patterns.length && deps.choosePackages) {
+        const picked = new Set(await deps.choosePackages(all));
+        chosen = all.filter((p) => picked.has(p.package));
+    }
+    const local = all.find((p) => p.package === LOCAL_PACKAGE)?.objects ?? 0;
+    if (!opts['include-local'])
+        chosen = chosen.filter((p) => p.package !== LOCAL_PACKAGE);
+    if (!chosen.length) {
+        throw new RegisterError(`No package chosen. ${all.length} customer packages exist; name them with --packages, e.g. --packages "ZFI_*,ZSD_*".`);
+    }
+    deps.print(`Pulling ${chosen.length} package${chosen.length === 1 ? '' : 's'}, checking each against the system's own count…`);
+    const pull = await pullBaseline(sql, { packages: chosen });
+    if (!pull.objects.length)
+        throw new RegisterError('Those packages hold no code objects. Nothing was written.');
+    const now = (deps.now ?? (() => new Date()))();
+    const projectId = projectIdFor(name, deps.rand);
+    const baselineText = `${JSON.stringify({ kind: 'baseline', formatVersion: 1, projectId, objects: pull.objects }, null, 1)}\n`;
+    const project = {
+        kind: 'team-project', formatVersion: 1, projectId, name, type, lead: { name: lead },
+        ...(system ? { system } : {}),
+        ...(atcVariant ? { atcVariant } : {}),
+        baseline: { file: BASELINE_FILE.replace(/\\/g, '/'), sha256: sha256(baselineText), takenAt: now.toISOString(), objectCount: pull.objects.length },
+        setAside: { local: opts['include-local'] ? 0 : local, generated: pull.setAside.generated, otherTypes: pull.setAside.otherTypes },
+        createdAt: now.toISOString(),
+    };
+    fs.mkdirSync(path.join(dir, 'baseline'), { recursive: true });
+    fs.writeFileSync(path.join(dir, BASELINE_FILE), baselineText);
+    fs.writeFileSync(path.join(dir, TEAM_FILE), `${JSON.stringify(project, null, 2)}\n`);
+    writeLanes(dir, projectId, []);
+    deps.print(`✓ ${name}: ${pull.objects.length} objects in ${chosen.length} packages. Every package matched the system's count.`);
+    deps.print(`  Set aside, not in scope: ${project.setAside.local} customer-named local ($TMP) entries of any type, ${pull.setAside.generated} generated, ${pull.setAside.otherTypes} non-code entries.`);
+    deps.print(`  Written to ${dir}`);
+    // F4: the live run of 2026-09-20 recorded the lead as "Admin" — the Windows
+    // user. That name goes into the team project file, into the writer id and
+    // into every record from then on. Said once, never asked.
+    if (!given && looksLikeAMachine(lead, deps)) {
+        deps.print(`  The lead is recorded as "${lead}". If that is not your name, run: cspeach team init … --lead "Your Name" next time, `
+            + `or edit "lead" in ${TEAM_FILE} now.`);
+    }
+    deps.print('  Next: cspeach team lane add <id> --owner "<name>" --packages "ZFI_*"   then each person: cspeach team join <folder>');
+    // The lead reads this top to bottom: what was pulled, what was measured, then
+    // what to do next. `join` has to RUN first — a record needs a writer id — but
+    // its advice belongs after the measurement, so its lines are held back.
+    const joinLines = [];
+    // The name the lead gave rides into `join` too, so the writer id, the records
+    // and every later `lane add` or `rule` on this laptop are all one person.
+    const joinedRc = join([dir], { ...deps, print: (l) => joinLines.push(l) }, given || undefined);
+    if (joinedRc !== 0) {
+        for (const l of joinLines)
+            deps.print(l);
+        return joinedRc;
+    }
+    await firstMeasurement(dir, project, pull.objects, opts, atc, deps);
+    for (const l of joinLines)
+        deps.print(l);
+    return 0;
+}
+/** Errors that are about this laptop's disk or the shared folder, never about SAP. */
+const CANNOT_WRITE = new Set(['EPERM', 'EACCES', 'EROFS', 'ENOSPC', 'EISDIR', 'ENOTEMPTY', 'EBUSY', 'EMFILE', 'ENOTDIR']);
+/**
+ * Measurement zero (D10): what the system finds on day one, taken by the lead
+ * into baseline/measurement-0.json through the same code as `refresh --all`.
+ * It is what "verified" is later measured AGAINST. It never fails `init`: the
+ * team project is already written, and a measurement can be taken any day.
+ *
+ * A clean estate DOES get a first measurement: a check run lists every object
+ * it covered, so an object it found nothing in has a row with no findings. Only
+ * an estate the run reports nothing back for at all — no object listed — leaves
+ * nothing to write, and then that is said out loud and `init` still succeeds.
+ */
+async function firstMeasurement(dir, project, baseline, opts, atc, deps) {
+    const LATER = 'Measure when you can: cspeach team refresh --all';
+    if (opts['no-measure']) {
+        deps.print('  Not measured (--no-measure). When you are ready: cspeach team refresh --all');
+        return;
+    }
+    if (!atc) {
+        deps.print('  Not measured yet: this connection cannot run ATC. When one can: cspeach team refresh --all');
+        return;
+    }
+    const variant = project.atcVariant;
+    if (!variant) {
+        deps.print('  Not measured yet: no ATC check variant was named. Name it and measure: cspeach team refresh --all --variant <NAME>');
+        return;
+    }
+    // The same Ctrl-C the run itself offers: what was measured before the press is still written.
+    const stop = new AbortController();
+    const off = onInterrupt(deps, () => {
+        if (stop.signal.aborted)
+            return;
+        deps.print('  Stopping. What has already been measured will still be written.');
+        deps.print('  Press Ctrl-C again to quit now.');
+        stop.abort();
+    });
+    try {
+        // A check run over a whole estate can take half an hour, and `init` has no
+        // time budget of its own. Say the size and the two ways out, before it starts.
+        deps.print(`Taking the first measurement with ${variant}: ${plural(baseline.length, 'object', 'objects')}.`);
+        deps.print('  This can take a while. Ctrl-C keeps what is measured; --no-measure skips it.');
+        const res = await measure({
+            joined: joinedOrThrow(), project, baseline, lanes: [], scope: { kind: 'all' }, variant, atc, by: { name: whoAmI(deps) },
+            dir: path.join(dir, 'baseline'), fileName: 'measurement-0.json',
+            ...(deps.now ? { now: deps.now() } : {}), ...(deps.rand ? { rand: deps.rand } : {}),
+            signal: stop.signal,
+            onProgress: progressLine(deps),
+        });
+        // The same block `refresh` prints, with one sentence said differently: a
+        // first measurement that proved nothing is not a failed command.
+        reportMeasurement(res, variant, deps, undefined, {
+            nothing: '  No first measurement was recorded: the check run reported no objects. Your team project is ready. '
+                + 'Run cspeach team refresh --all when you want to measure again.',
+        });
+        // Where it went, said so it cannot read as contradicting `join`'s outbox
+        // line: this one record belongs to the team project, not to this laptop.
+        if (res.file)
+            deps.print('  This first measurement is part of the team project\'s baseline, in the shared folder.');
+        const stoppedBy = res.stoppedBy ?? (stop.signal.aborted ? 'aborted' : undefined);
+        if (stoppedBy) {
+            const why = STOPPED_WORDS[stoppedBy];
+            deps.print(res.file
+                ? `  The first measurement ${why} before it finished, so it is partial. Measure the rest when you can: cspeach team refresh --all`
+                : `  The first measurement ${why} before anything was measured. ${LATER}`);
+        }
+    }
+    catch (e) {
+        // A folder CSPeach cannot write into is not a broken check run. Blaming the
+        // run would send the lead to look at SAP for a problem on their own disk.
+        const why = e instanceof Error ? e.message : String(e);
+        deps.print(CANNOT_WRITE.has(e?.code ?? '')
+            ? `  ! CSPeach could not write the first measurement into ${shown(dir)}: ${why}. The team project itself is complete.`
+            : `  ! The first measurement did not finish: ${why}. The team project is written. ${LATER}`);
+    }
+    finally {
+        off();
+    }
+}
+// ── join / leave ────────────────────────────────────────────────────────────
+/**
+ * `asName` is set only by `init --lead`: the lead's own name, so their writer
+ * id and their records carry it. `join` itself takes no such option — a
+ * developer's name comes from `CSPEACH_AUTHOR_NAME`, else `USER`/`USERNAME`.
+ */
+function join(args, deps, asName) {
+    const { positional, opts } = flags(args);
+    if (!positional[0])
+        throw new RegisterError('Usage: cspeach team join <team project folder> [--outbox <folder>]');
+    const projectDir = path.resolve(positional[0]);
+    const project = readProjectFile(projectDir);
+    const objects = readBaseline(projectDir).length; // also verifies the checksum
+    const state = loadState();
+    const outboxDir = path.resolve(opts.outbox ?? state.projects[project.projectId]?.outboxDir ?? defaultOutboxDir(project.projectId));
+    // A name given once is kept: joining again must not turn the lead back into
+    // whatever the machine calls them.
+    const saved = asName ?? state.projects[project.projectId]?.name;
+    const writerId = writerIdFor(saved ?? deps.identity().name, deps.machine?.());
+    fs.mkdirSync(path.join(outboxDir, 'writers', writerId, 'records'), { recursive: true });
+    state.projects[project.projectId] = { projectDir, outboxDir, writerId, ...(saved ? { name: saved } : {}) };
+    state.active = project.projectId;
+    saveState(state);
+    deps.print(`✓ Joined "${project.name}" (${objects} objects, lead ${project.lead.name}) as ${writerId}.`);
+    deps.print(`  Your own results are recorded on this laptop, in ${outboxDir}`);
+    deps.print('  CSPeach does not send them anywhere. Hand them in by copying that folder\'s "writers" folder into the team project folder,');
+    deps.print('  or keep the outbox inside your own synced folder: cspeach team join <folder> --outbox <folder>');
+    return 0;
+}
+function leave(deps) {
+    const state = loadState();
+    if (!state.active) {
+        deps.print('This laptop is not recording against a team project.');
+        return 0;
+    }
+    const was = state.active;
+    state.active = null;
+    saveState(state);
+    deps.print(`✓ Stopped recording against ${was}. Files already written stay where they are.`);
+    return 0;
+}
+// ── lane ────────────────────────────────────────────────────────────────────
+function lane(args, deps) {
+    const [verb, ...rest] = args;
+    const { positional, opts } = flags(rest);
+    const joined = joinedOrThrow();
+    const project = readProjectFile(joined.projectDir);
+    const lanes = readLanes(joined.projectDir);
+    if (verb === 'list' || !verb) {
+        if (!lanes.length)
+            deps.print('No lanes yet. cspeach team lane add <id> --owner "<name>" --packages "ZFI_*"');
+        for (const l of lanes)
+            deps.print(`${l.id.padEnd(12)} ${l.owner.padEnd(20)} ${[...l.packages, ...l.namePatterns.map((n) => `name:${n}`)].join(', ')}`);
+        return 0;
+    }
+    requireLead(project, deps);
+    const id = positional[0];
+    if (!id)
+        throw new RegisterError('Usage: cspeach team lane add <id> --owner "<name>" --packages "ZFI_*" [--names "ZCL_TAX_*"]  |  lane remove <id>');
+    if (verb === 'remove') {
+        writeLanes(joined.projectDir, project.projectId, lanes.filter((l) => l.id !== id));
+        deps.print(`✓ Lane ${id} removed.`);
+        return 0;
+    }
+    if (verb !== 'add')
+        throw new RegisterError('lane: use add, remove or list.');
+    const next = { id, owner: opts.owner ?? '', packages: list(opts.packages), namePatterns: list(opts.names) };
+    if (!next.owner || (!next.packages.length && !next.namePatterns.length)) {
+        throw new RegisterError('A lane needs --owner and at least one of --packages or --names.');
+    }
+    writeLanes(joined.projectDir, project.projectId, [...lanes.filter((l) => l.id !== id), next]);
+    const reg = registerFor(joined.projectDir, joined.outboxDir);
+    const mine = reg.register.lanes.find((l) => l.id === id);
+    // The count is every object this lane MATCHES, so it can never disagree with
+    // the overlap line under it (F2).
+    deps.print(`✓ Lane ${id}: ${next.owner}, ${plural(mine.objects, 'object', 'objects')}.`);
+    if (next.packages.length && next.namePatterns.length) {
+        deps.print(`  Lane ${id} means: in these packages AND matching these names.`);
+    }
+    if (reg.register.totals.overlapping)
+        deps.print(`  ! ${plural(reg.register.totals.overlapping, 'object now sits', 'objects now sit')} in more than one lane.`);
+    if (reg.register.totals.unowned)
+        deps.print(`  ${plural(reg.register.totals.unowned, 'object still has', 'objects still have')} no owner.`);
+    return 0;
+}
+// ── status ──────────────────────────────────────────────────────────────────
+function registerFor(projectDir, outboxDir) {
+    const project = readProjectFile(projectDir);
+    const collected = collectRecords(projectDir);
+    // This laptop's own outbox counts too, so a developer sees their work before
+    // handing it in. It is also the one way this picture can legitimately differ
+    // from the team project page's, so `status` says out loud when it counted them.
+    const own = outboxDir && path.resolve(outboxDir) !== path.resolve(projectDir) ? collectRecords(outboxDir) : { records: [], unreadable: 0, files: 0 };
+    const baseline = readBaseline(projectDir);
+    const lanes = readLanes(projectDir);
+    const register = buildRegister({ project, baseline, lanes, records: [...collected.records, ...own.records] });
+    return {
+        register, files: collected.files + own.files,
+        unreadable: collected.unreadable + own.unreadable, ownFiles: own.files,
+        // F2: a lanes.json written before names began to narrow packages holds
+        // fewer objects now. The lead is told, not left to work it out from a count.
+        narrowed: narrowedLanes(lanes, baseline),
+    };
+}
+const STATE_WORDS = [
+    ['verified', 'verified'], ['clean', 'clean'], ['claimed', 'claimed, not measured since'], ['working', 'in work'],
+    ['decided', 'decided, not started'], ['untouched', 'untouched'], ['did-not-hold', 'fix did not hold'],
+    ['regressed', 'regressed'], ['retired', 'retired'],
+];
+function status(args, deps) {
+    const { positional } = flags(args);
+    const joined = activeProject();
+    const projectDir = positional[0] ? path.resolve(positional[0]) : joined?.projectDir;
+    if (!projectDir)
+        throw new RegisterError('Usage: cspeach team status [<team project folder>]');
+    const project = readProjectFile(projectDir);
+    const { register: r, files, unreadable, ownFiles, narrowed } = registerFor(projectDir, positional[0] ? undefined : joined?.outboxDir);
+    const t = r.totals;
+    deps.print(`${project.name}  (${project.type}, lead ${project.lead.name})`);
+    // A clean sheet out of a file is somebody's export, not this system speaking.
+    // The words "verified" and "clean" do not change; the line says how many of
+    // them were measured one step removed, so nobody reads them as live proof.
+    const fromFile = t.fromFile.verified + t.fromFile.clean;
+    deps.print(`${t.objects} objects, ${t.active} active. ${t.decided} decided. `
+        + `${t.byState.verified} verified, ${t.byState.clean} clean`
+        + `${fromFile ? ` — ${fromFile} of them measured from a file` : ''}.`);
+    // The newest run that counted — by its time, not by the order the files were
+    // read in — so "from a file" is said of the run the date belongs to.
+    const lastRun = [...r.runs].reverse().find((run) => run.at === r.lastMeasuredAt);
+    deps.print(r.lastMeasuredAt
+        ? `Last measured ${r.lastMeasuredAt.slice(0, 16).replace('T', ' ')} UTC${lastRun?.basis === 'file' ? ', from a file' : ''}.`
+        : 'Not measured yet: "verified" and "clean" need an ATC run.');
+    deps.print('');
+    for (const [state, word] of STATE_WORDS)
+        if (t.byState[state])
+            deps.print(`  ${String(t.byState[state]).padStart(6)}  ${word}`);
+    deps.print('');
+    if (r.lanes.length) {
+        // The same columns, in the same order, as the team project page's lane table,
+        // counted with the same three functions. One lane must not read "50% done"
+        // in a browser and "3 done" here.
+        deps.print(`${'Lane'.padEnd(12)} ${'Owner'.padEnd(20)} Objects Active Proven  Last record`);
+        for (const l of r.lanes) {
+            deps.print(`${l.id.padEnd(12)} ${l.owner.padEnd(20)} ${String(l.objects).padStart(7)} `
+                + `${String(activeOf(l.objects, l.byState)).padStart(6)} ${String(provenOf(l.byState)).padStart(6)}  `
+                + `${l.lastRecordAt ? l.lastRecordAt.slice(0, 10) : 'nothing yet'}`);
+        }
+        // Said once per lane it is true of. A lane set up before this rule held
+        // both a package list and a name list, and took the whole package.
+        for (const id of narrowed)
+            deps.print(`Lane ${id} now means: in these packages AND matching these names.`);
+        deps.print('');
+    }
+    if (t.unowned)
+        deps.print(`! ${plural(t.unowned, 'object has', 'objects have')} no owner.`);
+    if (t.overlapping)
+        deps.print(`! ${plural(t.overlapping, 'object sits', 'objects sit')} in more than one lane.`);
+    if (t.conflicts) {
+        deps.print(`! ${plural(t.conflicts, 'object has a conflicting decision', 'objects have conflicting decisions')}.`
+            + ` The lead settles ${t.conflicts === 1 ? 'it' : 'each'} with: cspeach team rule <TYPE> <NAME> <decision>`);
+        for (const o of r.objects.filter((x) => x.decision?.conflict).slice(0, 10)) {
+            deps.print(`    ${o.key}: ${Object.entries(o.decision.conflict).map(([w, c]) => `${w} says ${c}`).join(', ')}`);
+        }
+    }
+    const s = r.skipped;
+    // Why this picture may be ahead of the one the team sees on the team project page.
+    if (ownFiles)
+        deps.print(`  Includes ${ownFiles} record file${ownFiles === 1 ? '' : 's'} from this laptop that ${ownFiles === 1 ? 'has' : 'have'} not been handed in yet.`);
+    if (unreadable)
+        deps.print(`  ${unreadable} of ${files} files could not be read yet (still syncing, or damaged).`);
+    // Read as JSON, but not a record: an export somebody dropped in, or a file a
+    // tool rewrote. It was counted and left out, and that is worth one line.
+    if (s.invalidRecords) {
+        deps.print(`  ${plural(s.invalidRecords, 'file', 'files')} in the folder could not be read`
+            + ` and ${s.invalidRecords === 1 ? 'was' : 'were'} left out.`);
+    }
+    if (s.rowsNotInBaseline) {
+        deps.print(`  ${plural(s.rowsNotInBaseline, 'row named an object', 'rows named objects')}`
+            + ` that ${s.rowsNotInBaseline === 1 ? 'is' : 'are'} not in this team project: ${r.unknownKeys.slice(0, 5).join(', ')}`);
+    }
+    if (s.otherProject)
+        deps.print(`  ${plural(s.otherProject, 'file belongs', 'files belong')} to another team project and ${s.otherProject === 1 ? 'was' : 'were'} ignored.`);
+    if (s.conflictingDuplicates)
+        deps.print(`  ${plural(s.conflictingDuplicates, 'file carries', 'files carry')} the id of another file but says something else. One of each pair was used.`);
+    if (s.rulingsNotFromLead)
+        deps.print(`  ${plural(s.rulingsNotFromLead, 'ruling was', 'rulings were')} not from the lead and ${s.rulingsNotFromLead === 1 ? 'was' : 'were'} ignored.`);
+    if (s.measurementsOtherVariant) {
+        // Naming our own variant is the difference between a lead who knows which
+        // run to redo and one who has to go and look in the folder.
+        const ours = project.atcVariant?.trim();
+        deps.print(`  ${plural(s.measurementsOtherVariant, 'measurement was', 'measurements were')} taken with another check variant`
+            + `${ours ? ` than this team project's (${ours})` : ''}`
+            + ` and ${s.measurementsOtherVariant === 1 ? 'was' : 'were'} ignored.`);
+        for (const g of r.ignoredRuns.slice(0, 5))
+            deps.print(`    ${g.at.slice(0, 16).replace('T', ' ')} UTC, ${g.by}, ${g.atcVariant}`);
+    }
+    return 0;
+}
+// ── refresh ─────────────────────────────────────────────────────────────────
+export const CANNOT_MEASURE = 'This laptop runs without a SAP system, so it cannot measure. Someone who is connected can run: cspeach team refresh. '
+    + 'Or read in an ATC result export: cspeach team refresh --from-file <file.csv>';
+const sameText = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
+/* ── The command line ───────────────────────────────────────────────────────
+ *
+ * `refresh` reads its own arguments, strictly. The loose parser the other verbs
+ * share turns `--all --lanes FI` into "measure everything" and
+ * `--packages "ZSD_*, ZFI_*"` into "measure ZSD_* only" — a half-scope that is
+ * then written down as a measurement of the whole. A command that cannot be
+ * sure what it was asked to measure must not measure anything.
+ */
+export const REFRESH_USAGE = 'Usage: cspeach team refresh (--lane <id> | --packages "ZFI_*,ZSD_*" | --all) '
+    + '[--variant <NAME>] [--force-variant] [--chunk <n>] [--max-minutes <n>] [--no-one-by-one] [--sap-alias <name>]\n'
+    + '   or: cspeach team refresh --from-file <file.csv> [--lane <id> | --packages "ZFI_*,ZSD_*" | --all] '
+    + '[--variant <NAME>] [--absent-means-clean]';
+/** Options that take a value, with the example each refusal shows. */
+const VALUE_OPTIONS = {
+    lane: '--lane sd',
+    packages: '--packages "ZFI_*,ZSD_*"',
+    variant: '--variant S4HANA_READINESS',
+    'max-minutes': '--max-minutes 20',
+    chunk: '--chunk 50',
+    'sap-alias': '--sap-alias S4H',
+    'from-file': '--from-file atc-export.csv',
+};
+const FLAG_OPTIONS = ['all', 'force-variant', 'no-one-by-one', 'absent-means-clean'];
+const KNOWN_OPTIONS = [...Object.keys(VALUE_OPTIONS), ...FLAG_OPTIONS];
+/** Options that describe a check RUN. A file was made by a run that is already over. */
+const RUN_ONLY_OPTIONS = ['chunk', 'max-minutes', 'no-one-by-one', 'sap-alias'];
+/** Edit distance, capped: only used to offer one guess at a mistyped option. */
+function near(typed, known = KNOWN_OPTIONS, max = 3) {
+    const distance = (a, b) => {
+        let prev = [...Array(b.length + 1).keys()];
+        for (let i = 1; i <= a.length; i += 1) {
+            const row = [i];
+            for (let j = 1; j <= b.length; j += 1) {
+                row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            }
+            prev = row;
+        }
+        return prev[b.length];
+    };
+    let best = null;
+    for (const name of known) {
+        const d = distance(typed, name);
+        if (d <= max && (!best || d < best.d))
+            best = { name, d };
+    }
+    return best ? best.name : null;
+}
+/**
+ * The same option twice. Which one a person meant cannot be guessed, and taking
+ * the last one silently is how half a scope gets measured and written down as
+ * the whole.
+ */
+const twice = (name) => `--${name} was given twice. Say it once.`;
+export function parseRefreshArgs(args) {
+    const no = (message) => ({ ok: false, message: `${message}\n${REFRESH_USAGE}` });
+    const opts = {};
+    const loose = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (!a.startsWith('--')) {
+            loose.push(a);
+            continue;
+        }
+        // `--lane=sd` is the same command as `--lane sd`. Read here, once, so the
+        // two spellings cannot be understood differently anywhere downstream.
+        const equals = a.indexOf('=');
+        if (equals > 2) {
+            const name = a.slice(2, equals);
+            const value = a.slice(equals + 1);
+            if (FLAG_OPTIONS.includes(name))
+                return no(`--${name} takes no value.`);
+            if (!(name in VALUE_OPTIONS)) {
+                const guess = near(name);
+                return no(`Unknown option --${name}.${guess ? ` Did you mean --${guess}?` : ''}`);
+            }
+            if (!value)
+                return no(`--${name} needs a value, for example: ${VALUE_OPTIONS[name]}`);
+            if (opts[name] !== undefined)
+                return no(twice(name));
+            opts[name] = value;
+            continue;
+        }
+        const name = a.slice(2);
+        if (FLAG_OPTIONS.includes(name)) {
+            if (opts[name] !== undefined)
+                return no(twice(name));
+            opts[name] = 'yes'; // a flag never eats the next word
+            continue;
+        }
+        if (!(name in VALUE_OPTIONS)) {
+            const guess = near(name);
+            return no(`Unknown option --${name}.${guess ? ` Did you mean --${guess}?` : ''}`);
+        }
+        const value = args[i + 1];
+        if (value === undefined || value.startsWith('--'))
+            return no(`--${name} needs a value, for example: ${VALUE_OPTIONS[name]}`);
+        if (opts[name] !== undefined)
+            return no(twice(name));
+        opts[name] = value;
+        i += 1;
+    }
+    if (loose.length) {
+        // The one that bites in real life: a space after the comma splits the list
+        // and the tail arrives on its own. Dropping it would measure half a scope.
+        if (opts.packages !== undefined) {
+            return no(`A package list is one word: --packages "ZFI_*,ZSD_*". "${loose[0]}" was left on its own`
+                + ' — put the list in quotes, or take the space out after the comma.');
+        }
+        return no(`cspeach team refresh does not take "${loose[0]}" on its own.`);
+    }
+    const given = ['all', 'lane', 'packages'].filter((k) => opts[k] !== undefined);
+    const fromFile = opts['from-file'];
+    if (fromFile === undefined) {
+        if (given.length !== 1)
+            return no('Say what to measure, one of: --lane <id>   --packages "ZFI_*,ZSD_*"   --all');
+        if (opts['absent-means-clean'] !== undefined) {
+            return no('--absent-means-clean is only for --from-file. A check run reports what it checked.');
+        }
+    }
+    else {
+        // A file is the result of a run that is already over: nothing about how a
+        // run would have been made can be honoured, so it is refused rather than
+        // quietly ignored.
+        if (!fromFile.trim())
+            return no(`--from-file needs a value, for example: ${VALUE_OPTIONS['from-file']}`);
+        if (given.length > 1)
+            return no('Name at most one of: --lane <id>   --packages "ZFI_*,ZSD_*"   --all');
+        for (const name of RUN_ONLY_OPTIONS) {
+            if (opts[name] !== undefined)
+                return no(`--${name} is about a live check run, so it means nothing with --from-file.`);
+        }
+        // One filtered export must never turn a whole lane clean by accident.
+        if (opts['absent-means-clean'] !== undefined && !given.length) {
+            return no('--absent-means-clean needs a scope: say which objects the file covers, '
+                + 'with --lane <id>, --packages "ZFI_*,ZSD_*" or --all.');
+        }
+    }
+    let scope = { kind: 'all' };
+    if (given[0] === 'lane') {
+        if (!opts.lane.trim())
+            return no(`--lane needs a value, for example: ${VALUE_OPTIONS.lane}`);
+        scope = { kind: 'lane', id: opts.lane.trim() };
+    }
+    else if (given[0] === 'packages') {
+        const patterns = list(opts.packages);
+        if (!patterns.length)
+            return no(`--packages needs a value, for example: ${VALUE_OPTIONS.packages}`);
+        scope = { kind: 'packages', patterns };
+    }
+    const value = {
+        scope, scopeGiven: given.length === 1,
+        forceVariant: opts['force-variant'] !== undefined,
+        oneByOne: opts['no-one-by-one'] === undefined,
+        absentMeansClean: opts['absent-means-clean'] !== undefined,
+        ...(fromFile !== undefined ? { fromFile: fromFile.trim() } : {}),
+    };
+    if (opts.variant !== undefined) {
+        const variant = opts.variant.trim().toUpperCase();
+        if (!variant)
+            return no(`--variant needs a value, for example: ${VALUE_OPTIONS.variant}`);
+        if (!VARIANT_NAME.test(variant))
+            return no(`"${opts.variant.trim()}" is not an ATC check variant name.`);
+        value.variant = variant;
+    }
+    if (opts['max-minutes'] !== undefined) {
+        const minutes = Number(opts['max-minutes']);
+        if (!Number.isFinite(minutes) || minutes <= 0)
+            return no(`--max-minutes must be a number of minutes greater than 0, for example: ${VALUE_OPTIONS['max-minutes']}`);
+        value.maxTotalMs = Math.round(minutes * 60000);
+    }
+    if (opts.chunk !== undefined) {
+        const chunk = Number(opts.chunk);
+        if (!Number.isInteger(chunk) || chunk <= 0)
+            return no(`--chunk must be a whole number of objects greater than 0, for example: ${VALUE_OPTIONS.chunk}`);
+        value.chunkSize = chunk;
+    }
+    if (opts['sap-alias'] !== undefined)
+        value.sapAlias = opts['sap-alias'];
+    return { ok: true, value };
+}
+/** The scope in words, for the line printed before a run that can take half an hour. */
+function scopeWords(scope) {
+    // `shown()`: the value is the person's own argument, and it still goes to a
+    // terminal through CSPeach.
+    if (scope.kind === 'lane')
+        return `lane ${shown(scope.id)}`;
+    if (scope.kind === 'packages')
+        return `packages ${shown(scope.patterns.join(', '))}`;
+    return 'the whole team project';
+}
+/**
+ * D6: one variant per team project.
+ *
+ * `persist` says the team project has no variant yet and this lead just chose
+ * one — but the name is NOT written here. A run that measures nothing (a typo,
+ * a dead VPN, a lane that does not exist) must leave the team project file
+ * exactly as it was; nothing in the family takes a variant name back.
+ */
+/**
+ * The variant a run may carry, given what the team project measures with.
+ * Throws the D6 refusal — the same sentence `measure()` refuses with, said in
+ * one place so a live run and a file import can never answer differently.
+ */
+function allowedVariant(ours, asked, force, asWritten = ours) {
+    // The team project file is a file like any other: it can be edited by hand,
+    // half-synced or filled in by something that was not CSPeach. A name SAP
+    // cannot accept never reaches SAP, and never reaches a record either.
+    if (!VARIANT_NAME.test(ours)) {
+        throw new RegisterError(`${TEAM_FILE} says this team project measures with "${shown(asWritten)}", `
+            + 'which is not an ATC check variant name. The lead must correct the file.');
+    }
+    if (!asked || asked === ours)
+        return { variant: ours, foreign: false };
+    if (!force)
+        throw new RegisterError(variantMismatchMessage(ours, asked));
+    return { variant: asked, foreign: true };
+}
+async function variantFor(project, opts, deps) {
+    const asked = opts.variant ?? '';
+    const ours = (project.atcVariant ?? '').trim().toUpperCase();
+    if (ours)
+        return { ...allowedVariant(ours, asked, opts.forceVariant, project.atcVariant ?? ours), persist: false };
+    const isLead = sameText(whoAmI(deps), project.lead.name);
+    let chosen = asked;
+    if (!chosen && isLead && deps.ask) {
+        chosen = (await deps.ask('Which ATC check variant does this team project measure with? (for example S4HANA_READINESS)')).trim().toUpperCase();
+    }
+    if (!chosen || !isLead)
+        throw new RegisterError(noVariantYetMessage(project.lead.name));
+    if (!VARIANT_NAME.test(chosen))
+        throw new RegisterError(`"${chosen}" is not an ATC check variant name.`);
+    return { variant: chosen, foreign: false, persist: true };
+}
+/** Why a run was refused, in words. `not-run` is said on its own: it never started. */
+const REFUSED_WORDS = {
+    incomplete: 'did not finish',
+    unmapped: 'held findings CSPeach could not tie to an object',
+    'no-object-list': 'gave an answer CSPeach could not read',
+    'run-not-started': 'did not start',
+    error: 'failed',
+    'not-run': 'was not started',
+};
+function progressLine(deps) {
+    return (p) => {
+        const note = p.note ? ` (${p.note})` : '';
+        if (p.phase === 'started')
+            deps.print(`  Run ${p.chunk} of ${p.chunks}: ${plural(p.objects, 'object', 'objects')}…${note}`);
+        else if (p.phase === 'refused')
+            deps.print(`  Run ${p.chunk} of ${p.chunks} ${REFUSED_WORDS[p.reason ?? 'error'] ?? 'failed'}.${note}`);
+    };
+}
+/**
+ * Every object that was asked for and did NOT get a row, with the reason in
+ * plain words. Only the buckets that hold something are printed: a line saying
+ * "0 not measured" teaches a person to skim past the ones that matter.
+ */
+/** Up to five of them, and an honest "…" for the rest. */
+const someNames = (names) => `${names.slice(0, 5).join(', ')}${names.length > 5 ? ', …' : ''}`;
+/**
+ * What an object the check run never reported means, in one sentence.
+ *
+ * A real run LISTS every object it covered, with no findings when it found
+ * none — that is what clean is. An object it does not list was not checked:
+ * this variant has no check for its type. So the sentence says the reason,
+ * rather than promising CSPeach is still working something out.
+ */
+export const absentLine = (count, names) => [
+    `  ! ${plural(count, 'object was', 'objects were')} not reported by the check run: this check variant has no check for their type. `
+        + `${count === 1 ? 'It is' : 'They are'} left as not measured.`,
+    ...(names.length ? [`    ${someNames(names)}`] : []),
+];
+function notMeasuredLines(res, deps, words = {}) {
+    if (res.absent) {
+        for (const line of words.absentLines?.(res.absent) ?? absentLine(res.absent, res.absentNames))
+            deps.print(line);
+    }
+    for (const c of res.refusedChunks) {
+        const words = REFUSED_WORDS[c.reason] ?? 'failed';
+        deps.print(`  ! Run ${c.index} ${words}. ${plural(c.objects, 'object', 'objects')} left as not measured.`);
+        if (c.detail)
+            deps.print(`    ${c.detail}`);
+    }
+    if (res.unsupported) {
+        deps.print(`  ! ${plural(res.unsupported, 'object', 'objects')} of a type this check cannot reach (left as not measured): `
+            + someNames(res.unsupportedNames));
+    }
+}
+export function reportMeasurement(res, variant, deps, foreignTo, words = {}) {
+    if (!res.file) {
+        deps.print(words.nothing ?? '✗ Nothing was measured, so nothing was written.');
+        for (const note of words.notes ?? [])
+            deps.print(note);
+        notMeasuredLines(res, deps, words);
+        return;
+    }
+    deps.print(words.headline ?? `✓ ${plural(res.measured, 'object measured', 'objects measured')}, ${res.withFindings} with findings.`);
+    // F3: SAP reports some findings twice — same place, same message, two finding
+    // ids. One problem in the code is one finding, so it is counted once; a
+    // person comparing this with their own ATC screen has to be told why the two
+    // numbers differ.
+    if (res.duplicateFindingsMerged) {
+        deps.print(`  SAP reported ${plural(res.duplicateFindingsMerged, 'finding', 'findings')} twice (same place, same message). CSPeach counts each once.`);
+    }
+    if (foreignTo) {
+        deps.print(`  ! Made with ${variant}, not the team project's ${foreignTo}. The record is kept, but it is not counted in the picture.`);
+    }
+    for (const note of words.notes ?? [])
+        deps.print(note);
+    notMeasuredLines(res, deps, words);
+    if (res.refusedRows.length) {
+        deps.print(`  ! ${plural(res.refusedRows.length, 'row named an object', 'rows named objects')}`
+            + ` that ${res.refusedRows.length === 1 ? 'is' : 'are'} not in this team project: ${res.refusedRows.slice(0, 5).join(', ')}`);
+    }
+    deps.print(`  Written to ${res.file}`);
+    deps.print('  Next: cspeach team status');
+}
+/** Why a run ended before it reached the end of the set, in plain words. */
+const STOPPED_WORDS = {
+    deadline: 'ran out of time',
+    aborted: 'was stopped',
+    connection: 'lost its connection to SAP',
+};
+/**
+ * I1, the product's main loop.
+ *
+ * An object the worklist never named gets no row, so its last measurement goes
+ * on driving its state. That is the safe direction and it stays. But when the
+ * object had findings, or somebody has claimed a fix on it and is waiting for a
+ * run to confirm it, "nothing happened" is exactly the wrong thing for a person
+ * to read: a fix that held would sit there as "did not hold" for ever. So the
+ * ones that matter are named.
+ *
+ * Objects only, never findings summed across them.
+ */
+function stillStanding(register, absentNames) {
+    if (!absentNames.length)
+        return [];
+    const wanted = new Set(absentNames);
+    return register.objects
+        .filter((o) => wanted.has(o.key) && ((o.openFindings ?? 0) > 0 || o.fixes.some((f) => f.status === 'fixed')))
+        .map((o) => o.key);
+}
+/**
+ * Ctrl-C stops the run between checks; nothing already measured is thrown away.
+ * `once`, on purpose: the SECOND press is Node's own, so a request that has
+ * hung can always be quit.
+ */
+function onInterrupt(deps, stop) {
+    if (deps.onInterrupt)
+        return deps.onInterrupt(stop);
+    const handler = () => stop();
+    process.once('SIGINT', handler);
+    return () => { process.off('SIGINT', handler); };
+}
+/**
+ * D8: proof for a team CSPeach cannot reach SAP from. Somebody exports the ATC
+ * result list from the system; this reads it in as a measurement, marked
+ * "measured from a file" everywhere it is shown. No connection is opened.
+ */
+function refreshFromFile(opts, deps) {
+    const joined = joinedOrThrow();
+    const project = readProjectFile(joined.projectDir);
+    const ours = (project.atcVariant ?? '').trim().toUpperCase();
+    const asked = opts.variant ?? '';
+    // The team project's own name is checked even when this run carries none: a
+    // variant the file on disk could not have got from SAP is somebody's edit.
+    const checked = ours ? allowedVariant(ours, asked, opts.forceVariant, project.atcVariant ?? ours) : { variant: asked, foreign: false };
+    // A file never SETS the team project's variant: that is the lead's decision,
+    // made on a live run. It may only carry a name the person vouched for.
+    const carried = asked ? checked : { variant: '', foreign: false };
+    if (opts.absentMeansClean) {
+        deps.print('  ! You told CSPeach that every object in this scope that the file does not mention is clean. CSPeach cannot check that.');
+    }
+    const res = measureFromFile({
+        joined, project, baseline: readBaseline(joined.projectDir), lanes: readLanes(joined.projectDir),
+        filePath: path.resolve(opts.fromFile), scope: opts.scopeGiven ? opts.scope : null,
+        ...(carried.variant ? { variant: carried.variant } : {}),
+        ...(opts.absentMeansClean ? { absentMeansClean: true } : {}),
+        by: { name: whoAmI(deps) }, ...(deps.now ? { now: deps.now() } : {}), ...(deps.rand ? { rand: deps.rand } : {}),
+    });
+    // Everything the file said that CSPeach did not use, and why. Each of these
+    // is a row that could have been proof and was not counted as any.
+    const notes = [];
+    // The gate: one finding CSPeach could not place is one finding that may
+    // belong to an object this file calls clean.
+    if (res.unplaced.length) {
+        notes.push(`  ! ${plural(res.unplaced.length, 'finding', 'findings')} in this file could not be matched to an object of this team project `
+            + `(${upToFive(res.unplaced)}), so CSPeach cannot take this file's word that anything is clean.`);
+    }
+    if (opts.absentMeansClean && !res.vouches) {
+        notes.push('  ! --absent-means-clean was not used: this file could not be read whole, '
+            + 'so CSPeach cannot take its word for the objects it does not mention.');
+    }
+    if (res.unknown.length) {
+        notes.push(`  ! ${plural(res.unknown.length, 'object in the file is', 'objects in the file are')} not in this team project `
+            + `and ${res.unknown.length === 1 ? 'was' : 'were'} left out: ${upToFive(res.unknown)}`);
+    }
+    const otherType = [...res.disagreed, ...res.ambiguous];
+    if (otherType.length) {
+        notes.push(`  ! ${plural(otherType.length, 'row names an object', 'rows name objects')} this team project does not have under that type, `
+            + `so ${otherType.length === 1 ? 'it was' : 'they were'} left out: ${upToFive(otherType)}`);
+    }
+    if (res.shortRows.length) {
+        notes.push(`  ! ${plural(res.shortRows.length, 'row was', 'rows were')} cut short and could not be read: `
+            + `${upToFive(res.shortRows.map((n) => `line ${n}`))}.`);
+    }
+    if (res.longRows.length) {
+        notes.push(`  ! ${plural(res.longRows.length, 'row has', 'rows have')} more cells than the header and could not be read: `
+            + `${upToFive(res.longRows.map((n) => `line ${n}`))}.`);
+    }
+    if (res.orphanFindings) {
+        notes.push(`  ! ${plural(res.orphanFindings, 'row names a finding', 'rows name findings')} with no object name, `
+            + 'so no object in this file could be read as clean.');
+    }
+    const blank = res.noObjectRows - res.orphanFindings;
+    if (blank > 0)
+        notes.push(`  ! ${plural(blank, 'row named', 'rows named')} no object and ${blank === 1 ? 'was' : 'were'} left out.`);
+    if (res.unknownColumns.length) {
+        const quoted = res.unknownColumns.map((c) => `"${c}"`);
+        const named = quoted.length === 1 ? `column ${quoted[0]}` : `columns ${upToFive(quoted)}`;
+        notes.push(`  ! CSPeach does not know the ${named}, so it cannot tell a clean object from a finding in this file.`);
+    }
+    if (res.outsideScope) {
+        notes.push(`  ! ${plural(res.outsideScope, 'row was', 'rows were')} outside the scope you named `
+            + `and ${res.outsideScope === 1 ? 'was' : 'were'} left out.`);
+    }
+    if (!carried.variant)
+        notes.push('  CSPeach cannot see which check variant made this file. Compare it only with files made the same way.');
+    reportMeasurement(res, carried.variant, deps, carried.foreign ? ours : undefined, {
+        headline: `✓ Read ${plural(res.fileRows, 'result row', 'result rows')} from ${shown(path.basename(opts.fromFile))}: `
+            + `${plural(res.measured, 'object', 'objects')} measured from a file, ${res.measured - res.withFindings} clean, `
+            + `${res.withFindings} with findings (${plural(res.findings, 'finding', 'findings')}).`,
+        nothing: res.unplaced.length || !res.vouches
+            ? '✗ Nothing in this file could be read as proof, so nothing was written.'
+            : opts.scopeGiven
+                ? '✗ Nothing in the file is in the scope you named, so nothing was written.'
+                : '✗ Nothing in the file matched an object in this team project, so nothing was written.',
+        notes,
+        absentLines: (count) => {
+            const lines = [];
+            const quiet = count - res.doubted.length;
+            if (quiet > 0) {
+                lines.push(`  ! ${plural(quiet, 'object in the scope you named is', 'objects in the scope you named are')} not mentioned in the file — left as not measured.`);
+                // Only when it is still on the table: telling a person to pass a flag
+                // that this file has just had taken off it is worse than saying nothing.
+                if (!opts.absentMeansClean) {
+                    lines.push('    A file that does not mention an object is not proof that it is clean. '
+                        + 'If the export covers every object in this scope, say so with --absent-means-clean.');
+                }
+            }
+            // Doubt, said by name: one row nobody could read is one object nobody may
+            // call clean, and a person can only act on a name.
+            if (res.doubted.length === 1) {
+                lines.push(`  ! A finding in this file may belong to ${res.doubted[0]}, so it was left as not measured.`);
+            }
+            else if (res.doubted.length) {
+                lines.push(`  ! A finding in this file may belong to any of ${res.doubted.length} objects, `
+                    + `so they were left as not measured: ${upToFive(res.doubted)}`);
+            }
+            return lines;
+        },
+    });
+    if (!res.file)
+        return 1;
+    // Live evidence outranks file evidence, per object. An import that changes no
+    // state is legal and is kept — but nobody should have to work that out from
+    // the picture afterwards, and no closing line may read as a fresh measurement.
+    const { register } = registerFor(joined.projectDir, joined.outboxDir);
+    const mine = new Set(res.keys);
+    const live = register.objects.filter((o) => mine.has(o.key) && o.measuredBasis === 'system').length;
+    if (live === res.measured)
+        deps.print('  The system has already measured every object in this file, so nothing in the picture changed. The record is kept.');
+    else if (live === 1)
+        deps.print('  1 of these objects has been measured from the system, so this file does not change its state.');
+    else if (live)
+        deps.print(`  ${live} of these objects have been measured from the system, so this file does not change their state.`);
+    return 0;
+}
+async function refresh(args, deps) {
+    // First, before anything that reads this laptop's state: a standalone laptop
+    // gets one honest sentence — unless it brought a file, which needs no system.
+    const broughtAFile = args.some((a) => a === '--from-file' || a.startsWith('--from-file='));
+    if (!broughtAFile && (deps.noSap || !deps.connect)) {
+        deps.print(CANNOT_MEASURE);
+        return 2;
+    }
+    const parsed = parseRefreshArgs(args);
+    if (!parsed.ok)
+        throw new RegisterError(parsed.message);
+    const opts = parsed.value;
+    if (opts.fromFile)
+        return refreshFromFile(opts, deps);
+    // Said twice on purpose: the check above lets a file through before the
+    // command line has been read, and this one is the one that guards the run.
+    if (deps.noSap || !deps.connect) {
+        deps.print(CANNOT_MEASURE);
+        return 2;
+    }
+    const { scope } = opts;
+    const joined = joinedOrThrow();
+    const project = readProjectFile(joined.projectDir);
+    const baseline = readBaseline(joined.projectDir);
+    const lanes = readLanes(joined.projectDir);
+    // Everything that can be settled on this laptop is settled before SAP is
+    // touched: the variant, the lane, and whether the scope holds anything.
+    const { variant, foreign, persist } = await variantFor(project, opts, deps);
+    const inScope = scopeObjects(baseline, lanes, scope);
+    if (!inScope.length)
+        throw new RegisterError(`Nothing in this team project matches ${scopeLabel(scope)}.`);
+    let atc;
+    try {
+        ({ atc } = await deps.connect(opts.sapAlias));
+    }
+    catch (e) {
+        // One line, the reason, no stack: "no system configured", a dead VPN and a
+        // wrong password all arrive here and all mean the same thing to the person.
+        deps.print(`✗ Could not connect to SAP: ${e instanceof Error ? e.message : String(e)}`);
+        return 2;
+    }
+    if (!atc) {
+        deps.print(CANNOT_MEASURE);
+        return 2;
+    }
+    deps.print(`Measuring ${scopeWords(scope)} with ${variant}: ${plural(inScope.length, 'object', 'objects')}.`);
+    const stop = new AbortController();
+    const off = onInterrupt(deps, () => {
+        if (stop.signal.aborted)
+            return;
+        deps.print('  Stopping. What has already been measured will still be written.');
+        deps.print('  Press Ctrl-C again to quit now.');
+        stop.abort();
+    });
+    let res;
+    try {
+        res = await measure({
+            joined, project, baseline, lanes, scope, variant, atc, by: { name: whoAmI(deps) },
+            ...(deps.now ? { now: deps.now() } : {}), ...(deps.rand ? { rand: deps.rand } : {}),
+            ...(opts.chunkSize ? { chunkSize: opts.chunkSize } : {}),
+            ...(opts.maxTotalMs ? { maxTotalMs: opts.maxTotalMs } : {}),
+            ...(opts.oneByOne ? {} : { oneByOne: false }),
+            // The variant was settled above; `measure()` checks it again and would
+            // otherwise refuse the run this command has already allowed — including
+            // the lead's first run, whose name is not on disk yet.
+            ...(foreign || persist ? { forceVariant: true } : {}),
+            signal: stop.signal,
+            onProgress: progressLine(deps),
+        });
+    }
+    finally {
+        off();
+    }
+    reportMeasurement(res, variant, deps, foreign ? (project.atcVariant ?? '').trim().toUpperCase() : undefined);
+    // The picture, once, for the two things said after the report. Built lazily:
+    // a refresh that measured nothing and reported nothing does not need it.
+    let merged = null;
+    const picture = () => (merged ??= registerFor(joined.projectDir, joined.outboxDir).register);
+    // I1: which of the objects the run did not report still have something
+    // standing against them. Their state has not moved, and that is worth saying.
+    const standing = res.absentNames.length ? stillStanding(picture(), res.absentNames) : [];
+    if (standing.length) {
+        deps.print(`  ! ${standing.length} of the objects the check run did not report had findings before `
+            + `or a fix waiting to be checked: ${upToFive(standing)}. Their state has not changed.`);
+    }
+    // The name is written only now: a run that measured something is the proof
+    // that SAP knows this variant.
+    if (res.file && persist) {
+        try {
+            writeProjectVariant(joined.projectDir, variant);
+            deps.print(`✓ This team project now measures with ${variant}.`);
+        }
+        catch (e) {
+            // The measurement is written and counts; only the team project file could
+            // not be updated, and that is a problem with a folder, not with the run.
+            deps.print(`  ! The measurement is written, but ${TEAM_FILE} could not be updated, so this team project still has no check variant. `
+                + `Ask the lead to try again: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    const stoppedBy = res.stoppedBy ?? (stop.signal.aborted ? 'aborted' : undefined);
+    if (stoppedBy) {
+        const why = STOPPED_WORDS[stoppedBy];
+        deps.print(res.file
+            ? `✗ The run ${why} before it finished. This measurement is partial.`
+            : `  The run ${why} before anything was measured.`);
+        return 3;
+    }
+    if (!res.file)
+        return 1;
+    // A claim whose rule no measurement has ever shown can never be confirmed or refuted. Say so now, by name.
+    const lost = picture().objects.flatMap((o) => o.fixes.filter((f) => f.status === 'fixed' && f.unmatchedRule).map((f) => `${o.key} (${f.rule})`));
+    if (lost.length) {
+        deps.print(`  ! ${plural(lost.length, 'claimed fix names', 'claimed fixes name')} a rule no measurement of that object has ever shown, `
+            + `so no measurement can confirm ${lost.length === 1 ? 'it' : 'them'}: ${lost.slice(0, 5).join(', ')}`);
+    }
+    return 0;
+}
+// ── outbox / rule ───────────────────────────────────────────────────────────
+function outbox(_args, deps) {
+    const joined = joinedOrThrow();
+    const dir = path.join(joined.outboxDir, 'writers', joined.writerId, 'records');
+    const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith('.json')).sort() : [];
+    deps.print(`Records this laptop has written for ${joined.projectId}: ${files.length}`);
+    deps.print(`  ${dir}`);
+    for (const f of files.slice(-15)) {
+        let rows = '?';
+        try {
+            rows = String(JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')).rows.length);
+        }
+        catch { /* listed anyway */ }
+        deps.print(`  ${f}  (${rows} rows)`);
+    }
+    deps.print('Each file is plain JSON: object names, decisions, statuses. No source code. Open one in Notepad to check.');
+    return 0;
+}
+function rule(args, deps) {
+    const { positional, opts } = flags(args);
+    const [type, name, classification] = positional;
+    if (!type || !name || !CLASSIFICATIONS.includes(classification)) {
+        throw new RegisterError(`Usage: cspeach team rule <TYPE> <NAME> ${CLASSIFICATIONS.join('|')} [--reason "<why>"]`);
+    }
+    const joined = joinedOrThrow();
+    requireLead(readProjectFile(joined.projectDir), deps);
+    const res = writeRecord(joined, 'ruling', [{ key: objectKey(type, name), classification, ...(opts.reason ? { reason: opts.reason } : {}) }], { name: whoAmI(deps) }, {
+        dir: path.join(joined.projectDir, 'rulings'), now: deps.now?.(),
+        ...(deps.rand ? { rand: deps.rand } : {}),
+    });
+    if (!res.file)
+        throw new RegisterError(`${objectKey(type, name)} is not in this team project's baseline.`);
+    deps.print(`✓ Ruled ${objectKey(type, name)} = ${classification}.`);
+    return 0;
+}