team 0.0.1 → 0.1.0

package/dist/commands/add.js

@@ -0,0 +1,445 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { approvalDifferences, budgetsInForce } from "../approve/approval.js";
+import { readArgs } from "../args.js";
+import { callerOf, describeCaller, isOwner, mayChangeTeam } from "../caller.js";
+import { blocksLaunch, doctorFindings, realSources as doctorSources } from "../commands/doctor.js";
+import { seatBudget } from "../budgets/gate.js";
+import { loadReadings } from "../budgets/readings.js";
+import { rulesOf } from "../commands/up.js";
+import { branchPresent, readMerge } from "../end/condition.js";
+import { clearStopped, hasSeat, restoreSeat, seatIsStopped } from "../file/lines.js";
+import { loadTeamFile, placedProblems } from "../file/load.js";
+import { validateTeamFile } from "../file/validate.js";
+import { writeTeamFile } from "../file/write.js";
+import { agentList, agentRename, paneRead, paneRun, sessionRunning, sessionState, startServer, workspaceClose, workspaceCreate, workspaceList, } from "../herdr.js";
+import { executePlan } from "../launch/execute.js";
+import { formatPlan, upPlan } from "../launch/plan.js";
+import { logLine } from "../log.js";
+import { profileFor } from "../profiles/index.js";
+import { emptySession, readState, updateState, withLock } from "../state.js";
+import { approvedCopy, readApproval, recordLedger, storePath } from "../store/store.js";
+import { launchLimit, readMachine } from "../watch/machine.js";
+import { readScreen } from "../watch/screen.js";
+import { seatStart } from "../worktree/place.js";
+const realLaunch = {
+    sessionState,
+    startServer,
+    sessionUp: sessionRunning,
+    createWorkspace: (session, cwd, label) => workspaceCreate(cwd, label, aim(session)),
+    paneRun: (session, pane, command) => paneRun(pane, command, aim(session)),
+    renameAgent: (session, pane, name) => agentRename(pane, name, aim(session)),
+    closeWorkspace: (session, workspace) => workspaceClose(workspace, aim(session)),
+    agentPanes(session) {
+        const agents = agentList(aim(session));
+        return agents === null ? null : agents.map((agent) => agent.pane);
+    },
+    paneText: (session, pane) => paneRead(pane, 200, aim(session)),
+    sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
+    now: () => new Date(),
+};
+function aim(session) {
+    return session === 'default' ? undefined : session;
+}
+export const realSources = {
+    home: homedir(),
+    sessionState,
+    agents: (session) => agentList(aim(session)),
+    workspaces(session) {
+        const listed = workspaceList(aim(session));
+        return listed === null ? null : listed.map((workspace) => ({ id: workspace.id, label: workspace.label }));
+    },
+    doctor: doctorSources,
+    machine: readMachine,
+    now: () => new Date(),
+    launch: realLaunch,
+};
+export const USAGE = `Usage: team add <name> [--dry-run] [--session <name>] [--file <path>]
+       team add --temporary --like <seat> --until <result:path|merged:branch> [--worktree <task>] [--dry-run] [--session <name>] [--file <path>]
+`;
+export const add = (argv, io) => runAdd(argv, io, realSources);
+export default add;
+export async function runAdd(argv, io, sources = realSources) {
+    const args = readArgs(argv, ['like', 'until', 'worktree', 'session', 'file'], ['temporary', 'dry-run']);
+    if (args.error) {
+        io.stderr(`team add: ${args.error}\n${USAGE}`);
+        return 2;
+    }
+    const temporary = args.flags.has('temporary');
+    if (temporary ? args.rest.length > 0 : args.rest.length !== 1) {
+        io.stderr(`team add: ${temporary ? `unexpected "${args.rest[0]}"` : 'a seat name is required'}\n${USAGE}`);
+        return 2;
+    }
+    if (!temporary && (args.values.like || args.values.until || args.values.worktree)) {
+        io.stderr('team add: --like, --until and --worktree are for --temporary\n');
+        return 2;
+    }
+    const loaded = loadTeamFile(io.cwd, args.values.file ? { file: args.values.file } : {});
+    if (!loaded.ok) {
+        for (const problem of loaded.errors)
+            io.stderr(`team add: ${where(problem)}${problem.message}\n`);
+        return 2;
+    }
+    const caller = callerOf(io);
+    if (args.values.file && !isOwner(caller)) {
+        io.stderr(`team add: --file is the owner's, from a terminal outside herdr; this call is ${describeCaller(caller)}\n`);
+        return 1;
+    }
+    if (!mayChangeTeam(caller, loaded.team)) {
+        io.stderr(`team add: only the owner, the coordinator or the operator runs it; this call is ${describeCaller(caller)}\n`);
+        return 1;
+    }
+    const { team, root, path } = loaded;
+    const session = args.values.session ?? team.session;
+    if (session === 'default') {
+        io.stderr('team add: session can\'t be "default", herdr\'s own session\n');
+        return 1;
+    }
+    const differences = approvalDifferences(team, root, sources.home);
+    if (differences === null) {
+        io.stderr('team add: the file was never approved on this machine: run `team approve`\n');
+        return 1;
+    }
+    if (differences.length) {
+        io.stderr(`team add: the file is not the approved one (${differences.join('; ')}): run \`team approve\`\n`);
+        return 1;
+    }
+    const approvedText = approvedCopy(root, sources.home);
+    const approved = approvedText ? validateTeamFile(approvedText) : null;
+    if (!approvedText || !approved?.ok) {
+        io.stderr('team add: the approved copy can\'t be read: run `team approve`\n');
+        return 1;
+    }
+    const dir = dirname(path);
+    const live = sources.sessionState(session);
+    if (live === null) {
+        io.stderr('team add: herdr doesn\'t answer\n');
+        return 1;
+    }
+    if (live === 'stopped') {
+        io.stderr(`team add: session ${session} is stopped; clear it with \`herdr session delete ${session}\`\n`);
+        return 1;
+    }
+    const agents = live === 'running' ? sources.agents(session) : [];
+    const workspaces = live === 'running' ? sources.workspaces(session) : [];
+    if (agents === null || workspaces === null) {
+        io.stderr(`team add: session ${session} runs, and its agents can't be read\n`);
+        return 1;
+    }
+    const recorded = readState(dir).sessions[session] ?? emptySession();
+    const ceilings = readApproval(storePath(team.project, root, sources.home))?.approval.ceilings;
+    if (!ceilings) {
+        io.stderr('team add: the file was never approved on this machine: run `team approve`\n');
+        return 1;
+    }
+    const original = readFileSync(path, 'utf8');
+    const built = temporary
+        ? temporarySeat(args.values, original, approved.team, recorded, agents, root, team.workspace.base)
+        : declaredSeat(args.rest[0] ?? '', original, approvedText, approved.team);
+    if ('error' in built) {
+        io.stderr(`team add: ${built.error}\n`);
+        return 1;
+    }
+    if (agents.some((agent) => agent.name === built.name)) {
+        io.stderr(`team add: ${built.name} is already running\n`);
+        return 1;
+    }
+    if (!profileFor(built.seat.cli)) {
+        io.stderr(`team add: no launch profile for \`${built.seat.cli}\` in this version\n`);
+        return 1;
+    }
+    const prepared = validateTeamFile(built.edited);
+    if (!prepared.ok) {
+        for (const problem of prepared.errors)
+            io.stderr(`team add: ${where(problem)}${problem.message}\n`);
+        return 2;
+    }
+    for (const problem of placedProblems(prepared.team, root)) {
+        io.stderr(`team add: ${problem.message}\n`);
+        return 1;
+    }
+    // Where the seat waits: its own folder, the lobby, or a refusal — before the file is edited.
+    const start = seatStart(prepared.team, built.seat, root);
+    if ('problem' in start) {
+        io.stderr(`team add: ${start.problem}\n`);
+        return 1;
+    }
+    const doctorTeam = built.temporary
+        ? { ...prepared.team, seats: prepared.team.seats.map((item) => item.name === built.temporary?.like ? { ...item, stopped: false } : item) }
+        : prepared.team;
+    for (const finding of doctorFindings(doctorTeam, root, dir, session, sources.doctor, prepared.warnings)) {
+        if (blocksLaunch(finding)) {
+            io.stderr(`team add: ${finding.text}\n`);
+            return 1;
+        }
+    }
+    const samples = [];
+    const crossed = () => {
+        const machine = sources.machine?.(root);
+        return machine ? launchLimit(machine, team.machine, samples, sources.now().getTime()) : null;
+    };
+    const problem = crossed();
+    if (problem) {
+        io.stderr(`team add: ${problem}\n`);
+        return 1;
+    }
+    const running = runningOf(agents, prepared.team, recorded);
+    const room = ceilingProblem(ceilings, running, built.seat, Boolean(built.temporary));
+    if (room) {
+        io.stderr(`team add: ${room}\n`);
+        return 1;
+    }
+    const again = crossed();
+    if (again) {
+        io.stderr(`team add: ${again}\n`);
+        return 1;
+    }
+    // The gate reads the approved budgets, never the edited file's: the seat this `add` inserts
+    // changes no section of its own, and no unapproved reserve may unblock a launch (#50).
+    const budgets = budgetsInForce(prepared.team, root, sources.home);
+    const decision = seatBudget(budgets, loadReadings(dir, session), built.seat, sources.now().getTime());
+    const stray = unnamedIn(built.seat.label, agents, workspaces);
+    const starting = seatPlan(prepared.team, built.seat, start);
+    const planned = stray
+        ? { ...starting, stage: 'launched', pane: stray.pane, workspace: stray.workspace, agentLive: true }
+        : starting;
+    const wouldLaunch = planned.stage === undefined || !planned.pane || (planned.stage === 'launched' && !planned.agentLive);
+    const seatForPlan = decision.kind === 'refuse' && !wouldLaunch ? { ...planned, budget: decision } : planned;
+    const dry = args.flags.has('dry-run');
+    if (dry) {
+        if (decision.kind === 'refuse' && wouldLaunch) {
+            io.stdout(`${built.name}: would refuse: ${decision.why}\ndry run: nothing was run\n`);
+            return 0;
+        }
+        if (decision.kind === 'unknown')
+            io.stdout(`${built.name}: ${decision.text}\n`);
+        const preview = upPlan({
+            root,
+            session,
+            sessionRunning: live === 'running',
+            seats: [seatForPlan],
+            watchAlive: true,
+        });
+        io.stdout(formatPlan(preview));
+        return 0;
+    }
+    if (decision.kind === 'refuse' && wouldLaunch) {
+        io.stderr(`team add: refused: ${decision.why}\n`);
+        return 1;
+    }
+    if (decision.kind === 'unknown')
+        io.stdout(`${built.name}: ${decision.text}\n`);
+    if (built.edited !== original) {
+        const written = withLock(dir, () => {
+            if (readFileSync(path, 'utf8') !== original)
+                return { kind: 'changed' };
+            const wrote = writeTeamFile(path, built.edited);
+            return wrote.ok ? { kind: 'ok' } : { kind: 'invalid', errors: wrote.errors };
+        });
+        if (written.kind === 'changed') {
+            io.stderr('team add: the file changed while add was checking; nothing was written\n');
+            return 1;
+        }
+        if (written.kind === 'invalid') {
+            for (const problem of written.errors)
+                io.stderr(`team add: ${where(problem)}${problem.message}\n`);
+            return 2;
+        }
+    }
+    const plan = upPlan({ root, session, sessionRunning: live === 'running', seats: [seatForPlan], watchAlive: true });
+    const who = describeCaller(caller);
+    const host = hostOf({
+        dir, session, team: prepared.team, root, ceilings, running, seat: built.seat, temporary: built.temporary,
+        caller: who, now: sources.now, launch: sources.launch, readMachine: sources.machine, samples, limits: team.machine, io,
+    });
+    const report = await executePlan(plan, session, host);
+    const afterwards = readState(dir).sessions[session]?.seats[built.name];
+    if (afterwards?.stage === 'ready' && built.temporary) {
+        recordLedger(storePath(team.project, root, sources.home), [built.seat]);
+    }
+    const ready = afterwards?.stage === 'ready';
+    if (ready)
+        logLine(dir, 'add', who, `started ${built.name}${built.temporary ? ` like ${built.temporary.like} until ${built.temporary.until}` : ''}`, sources.now());
+    return ready && !report.serverFailed ? 0 : 1;
+}
+function declaredSeat(name, current, approvedText, approved) {
+    const seat = approved.seats.find((item) => item.name === name);
+    if (!seat)
+        return { error: `the approved file has no seat ${JSON.stringify(name)}` };
+    let edited = hasSeat(current, name) ? current : restoreSeat(current, approvedText, name);
+    if (seat.stopped || seatIsStopped(edited, name))
+        edited = clearStopped(edited, name);
+    const again = validateTeamFile(edited);
+    const restored = again.ok ? again.team.seats.find((item) => item.name === name) : undefined;
+    if (!restored)
+        return { error: `couldn't put ${name} back from the approved copy` };
+    return { name, seat: { ...restored, stopped: false }, edited, temporary: undefined };
+}
+function temporarySeat(values, current, approved, state, agents, root, base) {
+    const like = approved.seats.find((item) => item.name === values.like);
+    if (!like)
+        return { error: `the approved file has no seat ${JSON.stringify(values.like)}` };
+    const until = parseUntil(values.until ?? '');
+    if (!until)
+        return { error: '--until is result:<path> or merged:<branch>' };
+    let own;
+    if (until.kind === 'result') {
+        if (until.path.startsWith('/') || until.path.startsWith('~'))
+            return { error: 'a result path is relative to the project' };
+        if (existsSync(resolve(root, until.path)))
+            return { error: `${until.path} already exists` };
+    }
+    else if (!base) {
+        return { error: 'workspace.base is required to read a merged end' };
+    }
+    else {
+        const read = readMerge(root, until.branch, base, false);
+        const here = branchPresent(root, until.branch);
+        if (read.detail.includes('the branch is gone') || here === false)
+            return { error: `branch ${until.branch} doesn't exist` };
+        if (here !== true && read.verdict === 'unproven')
+            return { error: read.detail };
+        own = read.ownNow > 0;
+    }
+    const task = values.worktree;
+    const worktree = task ? state.worktrees[task] : undefined;
+    if (task && !worktree)
+        return { error: `no worktree named ${JSON.stringify(task)} is recorded` };
+    if (worktree?.setup === 'failed')
+        return { error: `worktree ${task} has a failed setup; team worktree remove ${task}` };
+    const name = temporaryName(like.name, approved, state, agents);
+    return {
+        name,
+        edited: current,
+        seat: { ...like, name, label: name, cwd: worktree?.path ?? like.cwd, stopped: false },
+        temporary: {
+            like: like.name,
+            until: values.until ?? '',
+            ...(task ? { task } : {}),
+            ...(until.kind === 'merged' && !task && own !== undefined ? { own_commits: own } : {}),
+        },
+    };
+}
+function temporaryName(like, team, state, agents) {
+    const used = new Set([...team.seats.map((seat) => seat.name), ...Object.keys(state.seats), ...agents.map((agent) => agent.name ?? '')]);
+    let n = 1;
+    while (used.has(`${like}-tmp-${n}`))
+        n++;
+    return `${like}-tmp-${n}`;
+}
+function parseUntil(value) {
+    if (value.startsWith('result:') && value.length > 'result:'.length)
+        return { kind: 'result', path: value.slice('result:'.length) };
+    if (value.startsWith('merged:') && value.length > 'merged:'.length)
+        return { kind: 'merged', branch: value.slice('merged:'.length) };
+    return null;
+}
+function seatPlan(team, seat, start) {
+    return {
+        name: seat.name,
+        cli: seat.cli,
+        launch: seat.launch,
+        cwd: start.cwd,
+        label: seat.label,
+        stopped: false,
+        rules: rulesOf(team, seat),
+        ...(start.lobby ? { lobby: true } : {}),
+    };
+}
+function unnamedIn(label, agents, workspaces) {
+    const ids = new Set(workspaces.filter((workspace) => workspace.label === label).map((workspace) => workspace.id));
+    return agents.find((agent) => !agent.name && ids.has(agent.workspace));
+}
+function runningOf(agents, team, state) {
+    const seats = new Map(team.seats.map((seat) => [seat.name, seat]));
+    const running = [];
+    for (const agent of agents) {
+        if (!agent.name)
+            continue;
+        const seat = seats.get(agent.name);
+        const known = state.seats[agent.name];
+        if (!seat && !known?.temporary)
+            continue;
+        const like = known?.temporary ? seats.get(known.temporary.like) : undefined;
+        running.push({ name: agent.name, vendor: seat?.vendor ?? like?.vendor ?? 'unknown', temporary: Boolean(known?.temporary) });
+    }
+    return running;
+}
+function ceilingProblem(ceilings, running, seat, temporary) {
+    if (running.some((item) => item.name === seat.name))
+        return null;
+    if (running.length + 1 > ceilings.seats)
+        return `the approval allows ${ceilings.seats} seats; ${running.length + 1} would be running`;
+    if (temporary && running.filter((item) => item.temporary).length + 1 > ceilings.temporary) {
+        return `the approval allows ${ceilings.temporary} temporary seats; ${running.filter((item) => item.temporary).length + 1} would be running`;
+    }
+    const cap = ceilings.vendors[seat.vendor];
+    if (cap !== undefined) {
+        const vendors = running.filter((item) => item.vendor === seat.vendor).length + 1;
+        if (vendors > cap)
+            return `the approval allows ${cap} ${seat.vendor} seats; ${vendors} would be running`;
+    }
+    return null;
+}
+function where(problem) {
+    return problem.line ? `line ${problem.line}: ` : '';
+}
+function hostOf(input) {
+    const { dir, session, launch, seat, temporary } = input;
+    const running = [...input.running];
+    return {
+        startServer: launch.startServer,
+        sessionUp: launch.sessionUp,
+        makeDir(path) {
+            try {
+                mkdirSync(path, { recursive: true });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        createWorkspace: launch.createWorkspace,
+        paneRun: launch.paneRun,
+        typeLine: () => false,
+        renameAgent: launch.renameAgent,
+        closeWorkspace: launch.closeWorkspace,
+        stopSession: () => false,
+        kill: () => false,
+        agentPanes: launch.agentPanes,
+        classify: (_name, pane, cli) => readScreen(cli, launch.paneText(session, pane) ?? undefined).kind,
+        sleep: launch.sleep,
+        now: () => input.now().getTime(),
+        allow(name) {
+            if (input.readMachine) {
+                const problem = launchLimit(input.readMachine(input.root), input.limits, input.samples, input.now().getTime());
+                if (problem)
+                    return problem;
+            }
+            if (name !== seat.name)
+                return null;
+            return ceilingProblem(input.ceilings, running, seat, Boolean(temporary));
+        },
+        record(name, patch) {
+            updateState(dir, (file) => {
+                const current = (file.sessions[session] ??= emptySession());
+                const prior = current.seats[name] ?? { stage: patch.stage };
+                current.seats[name] = { ...prior, ...patch, ...(temporary && name === seat.name ? { temporary } : {}) };
+            });
+        },
+        running(name) {
+            if (!running.some((item) => item.name === name))
+                running.push({ name, vendor: seat.vendor, temporary: Boolean(temporary) });
+        },
+        drop(name) {
+            updateState(dir, (file) => {
+                const seats = file.sessions[session]?.seats;
+                if (seats)
+                    delete seats[name];
+            });
+        },
+        say: (line) => input.io.stdout(line),
+        log: (who, what) => logLine(dir, 'add', input.caller, `${who}: ${what}`, input.now()),
+    };
+}

package/dist/commands/approve.d.ts

@@ -0,0 +1,11 @@
+import type { Command, Io } from '../io.ts';
+export type ApproveSources = {
+    ask(question: string): Promise<string | null>;
+    now(): Date;
+    home: string;
+};
+export declare const realSources: ApproveSources;
+export declare const USAGE = "Usage: team approve [--show] [--file <path>]\n";
+export declare const approve: Command;
+export default approve;
+export declare function runApprove(argv: string[], io: Io, sources: ApproveSources): Promise<number>;

package/dist/commands/approve.js

@@ -0,0 +1,146 @@
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve, sep } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { approvedFingerprints, approvalOf, ceilingsOf } from "../approve/approval.js";
+import { checkDrift, resolveChecks } from "../budgets/checks.js";
+import { formatDiff } from "../approve/diff.js";
+import { compare, describe, fingerprints } from "../approve/fingerprint.js";
+import { readArgs } from "../args.js";
+import { callerOf, describeCaller, isOwner } from "../caller.js";
+import { loadTeamFile, placedProblems } from "../file/load.js";
+import { validateTeamFile } from "../file/validate.js";
+import { logLine } from "../log.js";
+import { readApproval, storePath, writeApproval } from "../store/store.js";
+export const realSources = {
+    async ask(question) {
+        const terminal = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            return await terminal.question(question);
+        }
+        catch {
+            return null;
+        }
+        finally {
+            terminal.close();
+        }
+    },
+    now: () => new Date(),
+    home: homedir(),
+};
+export const USAGE = 'Usage: team approve [--show] [--file <path>]\n';
+export const approve = (argv, io) => runApprove(argv, io, realSources);
+export default approve;
+function real(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+function inside(path, folder) {
+    return path === folder || path.startsWith(folder.endsWith(sep) ? folder : folder + sep);
+}
+// The store must stay out of the project and of every folder a seat may work in.
+function storeProblem(store, root, team) {
+    const place = real(dirname(store));
+    const folders = [root, ...team.trust.map((pattern) => resolve(root, pattern.replace(/\/?\*$/, '')))];
+    const holder = folders.map(real).find((folder) => inside(place, folder) || inside(store, folder));
+    return holder === undefined ? null : `the approval store ${store} is inside ${holder}, where seats work`;
+}
+function ceilingsLine(ceilings) {
+    const vendors = Object.entries(ceilings.vendors).map(([vendor, count]) => `${vendor} ${count}`);
+    return [`${ceilings.seats} seats at most`, `${ceilings.temporary} temporary`, ...vendors].join(', ');
+}
+export async function runApprove(argv, io, sources) {
+    const args = readArgs(argv, ['file'], ['show']);
+    if (args.error || args.rest.length) {
+        io.stderr(`team approve: ${args.error ?? `unexpected "${args.rest[0]}"`}\n${USAGE}`);
+        return 2;
+    }
+    const loaded = loadTeamFile(io.cwd, args.values.file ? { file: args.values.file } : {});
+    if (!loaded.ok) {
+        for (const problem of loaded.errors) {
+            io.stderr(`team approve: ${problem.line ? `line ${problem.line}: ` : ''}${problem.message}\n`);
+        }
+        return 2;
+    }
+    // Validate the text load just read. A second read could store an edit under the first read's fingerprints.
+    const checked = validateTeamFile(loaded.text);
+    if (!checked.ok) {
+        for (const problem of checked.errors) {
+            io.stderr(`team approve: ${problem.line ? `line ${problem.line}: ` : ''}${problem.message}\n`);
+        }
+        return 2;
+    }
+    const placed = placedProblems(checked.team, loaded.root);
+    if (placed.length) {
+        for (const problem of placed)
+            io.stderr(`team approve: ${problem.message}\n`);
+        return 2;
+    }
+    const { team } = checked;
+    const { root, path } = loaded;
+    const text = loaded.text;
+    for (const warning of checked.warnings)
+        io.stderr(`team approve: warning, line ${warning.line}: ${warning.message}\n`);
+    const store = storePath(team.project, root, sources.home);
+    const problem = storeProblem(store, root, team);
+    if (problem) {
+        io.stderr(`team approve: ${problem}\n`);
+        return 1;
+    }
+    const resolved = resolveChecks(team, root, process.env.PATH ?? '');
+    if (!resolved.ok) {
+        io.stderr(`team approve: the check for ${resolved.account} cannot be resolved\n`);
+        return 1;
+    }
+    const previous = readApproval(store);
+    const ceilings = ceilingsOf(team);
+    const seats = team.seats.length;
+    if (previous === null) {
+        io.stdout(`${path}: never approved on this machine. The whole file:\n\n`);
+        io.stdout(`${text
+            .replace(/\n$/, '')
+            .split('\n')
+            .map((line, index) => `  ${index + 1}: ${line}`)
+            .join('\n')}\n\n`);
+    }
+    else {
+        const changes = [
+            ...compare(approvedFingerprints(previous), fingerprints(team)).map(describe),
+            ...checkDrift(previous.approval.checks, resolved.checks),
+        ];
+        const lines = formatDiff(previous.file, text);
+        if (lines.length === 0)
+            io.stdout(`${path}: the same text as the copy approved on ${previous.approval.approvedAt}.\n\n`);
+        else {
+            io.stdout(`${path}: against the copy approved on ${previous.approval.approvedAt}:\n\n`);
+            io.stdout(`${lines.map((line) => `  ${line}`).join('\n')}\n\n`);
+        }
+        io.stdout(changes.length ? `Needs a new approval: ${changes.join('; ')}.\n` : 'Nothing in it needs a new approval.\n');
+        if (ceilingsLine(previous.approval.ceilings) !== ceilingsLine(ceilings)) {
+            io.stdout(`Ceilings approved: ${ceilingsLine(previous.approval.ceilings)}.\n`);
+        }
+    }
+    io.stdout(`Ceilings this approval fixes: ${ceilingsLine(ceilings)}.\n`);
+    io.stdout(`Seats: ${seats} (${team.seats.map((seat) => seat.name).join(', ')}).\n`);
+    if (args.flags.has('show'))
+        return 0;
+    const caller = callerOf(io);
+    if (!isOwner(caller)) {
+        io.stderr(`team approve: only the owner approves a team file, from a terminal outside herdr; this call is ${describeCaller(caller)}\n`);
+        return 1;
+    }
+    const answer = await sources.ask(`\nType the number of seats (${seats}) to approve this file, and its commands and rules, to run: `);
+    if (answer === null || answer.trim() !== String(seats)) {
+        io.stderr('team approve: not approved; nothing was written\n');
+        return 1;
+    }
+    const now = sources.now();
+    writeApproval(store, { approval: approvalOf(team, root, now, resolved.checks), file: text }, team.seats);
+    logLine(dirname(path), 'approve', describeCaller(caller), `approved ${seats} seats; ceilings: ${ceilingsLine(ceilings)}`, now);
+    io.stdout(`Approved. The record is in ${store}; check the rest with \`team doctor\`.\n`);
+    return 0;
+}

package/dist/commands/check.d.ts

@@ -0,0 +1,17 @@
+import { type CheckConfig } from '../check/config.ts';
+import type { Problem } from '../file/types.ts';
+import type { Io } from '../io.ts';
+export type LoadConfig = (cwd: string, file?: string) => {
+    ok: true;
+    config: CheckConfig;
+    warnings: Problem[];
+} | {
+    ok: false;
+    errors: Problem[];
+    path?: string;
+};
+export declare const USAGE = "Usage: team check <ref> [--pr <file>] [--since <ref>] [--file <path>]\n\n  <ref>            a range when it holds \"..\", passed to git as given\n                   (origin/main..HEAD); otherwise that one commit\n  --pr <file>      also check a pull request's body (\"-\" reads standard input)\n  --since <ref>    skip this commit and everything reachable from it, for this\n                   run; overrides identity.since\n  --file <path>    the team file, instead of .agents/team.yaml\n\nExits 0 when every commit passes, 1 when one is refused, 2 when the check\ncan't run.\n";
+/** The file's rules, with the ledger of this machine's store when the owner has approved a file here. */
+export declare function loadConfig(cwd: string, file?: string, home?: string): ReturnType<LoadConfig>;
+export declare function check(argv: string[], io: Io, load?: LoadConfig): Promise<number>;
+export default check;