team 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Floor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,310 @@
+# team
+
+Set up, change and watch a project's team of AI agents from one file.
+
+`team` is a small command-line tool with no runtime dependencies. A project declares its team in
+`.agents/team.yaml`: the seats, the model each one runs, how each agent signs its work, the rules it
+works under, the folders it may touch. Commands then check that file against a machine, a session
+and a history, and build and watch the team itself. Version 0.1 runs teams in
+[herdr](https://herdr.dev).
+
+**Status: 0.1, early: herdr only; trust is specified, not built yet.** This build parses and
+validates the file, checks who is calling, and holds `add`, `approve`, `check`, `doctor`, `down`,
+`init`, `remove`, `status`, `up`, `watch` and `worktree`.
+
+## Install
+
+Node 22 or later runs the built command.
+
+```sh
+npm install -g team       # or run it without installing: npx team
+team --version            # 0.1.0
+```
+
+## The file is private to each clone
+
+`team init` keeps `.agents/team.yaml` out of git through `.git/info/exclude`, never by editing
+`.gitignore`: a public repository shouldn't carry its roster. A fresh clone therefore has no team
+file. Run `team init` to write one, or `team init --restore` to bring back the copy you last
+approved on this machine. A file you receive from someone else runs nothing until you approve it
+yourself.
+
+## The file's format
+
+A documented subset of YAML, read by the library's own parser: maps, lists, one-line `{ }` and
+`[ ]`, plain and quoted values, comments. Anchors, aliases, tags, block scalars, several documents
+in one file and duplicate keys are refused, with the line number. The file starts with `format: 1`.
+By example:
+
+```yaml
+format: 1                     # the only format this version reads
+project: hello
+coordinator: claude-coord     # the seat that dispatches work
+operator: claude-coord        # the seat the watch reports to
+
+identity:
+  signature:
+    commits:
+      position: trailer       # last-line | trailer | anywhere
+      exempt: [merge]         # merge commits need no signature
+
+rules:                        # lines added to every seat's rules at launch
+  - Run the tests your change touches, not the whole suite.
+
+workspace:
+  mode: shared                # shared | worktree: the default for every seat
+
+seats:
+  - role: coordinator
+    name: claude-coord
+    cli: claude-code          # the launch profile
+    vendor: anthropic         # the model's maker
+    model: Claude Opus        # the model's name, without its version
+    version: "5.5"            # the release alone, quoted
+    launch: claude --model claude-opus-5-5   # no approval flags: the profile adds them
+
+  - role: implementer
+    name: codex-hello
+    cli: codex
+    vendor: openai
+    model: GPT Sol
+    version: "6"
+    display: GPT-6 Sol        # the vendor's spelling, for the signature
+    launch: codex -m gpt-6-sol -c model_reasoning_effort=high
+    parked: true              # running, and not reported while idle
+
+  - role: implementer
+    name: deepseek-hello
+    cli: claude-code          # DeepSeek's model, run by Claude Code
+    vendor: deepseek
+    model: DeepSeek Flash
+    version: "V4.1"
+    display: DeepSeek V4.1 Flash
+    launch: team-deepseek     # a launcher on the PATH, holding the account's key and endpoint
+    count: 2                  # deepseek-hello and deepseek-hello-2
+
+  - role: reviewer
+    name: grok-hello
+    cli: grok
+    vendor: xai
+    model: Grok
+    version: "4.7"
+    launch: grok --model grok-4.7
+    stopped: true             # kept in the file; `up` doesn't start it
+```
+
+- `session` names the herdr session and defaults to `project`; `--session` overrides it.
+- `coordinator` and `operator` name seats: the coordinator dispatches work, the operator receives
+  the watch's reports and nudges.
+- `identity.signature` is the rule `check` enforces: a template, where it must stand, and which
+  commits are exempt. Commit signatures read `Agent: {display} · {role}`, pull request bodies
+  `**Agent:** {display} · {role}`. Without `display`, the signature reads "model version"; with it,
+  the vendor's own spelling. `identity.since` skips an older history, `identity.humans` lists commit
+  authors who don't sign, and `identity.forbidden` adds to the defaults — `^Claude-Session:` lines
+  and session links are always refused.
+- `seats[*].cli` picks the launch profile; `claude-code`, `codex`, `cursor` and `antigravity` are available, and `team
+  doctor` says what the others still need. `vendor`, `model` and `version` spell one seat's model.
+- `launch` is the plain command, without approval flags: the profile adds them. `count: 2` makes the
+  numbered names; `parked` keeps a seat out of idle reports, `stopped` keeps it out of `up`.
+- `workspace.mode` is `shared` (every seat in the project) or `worktree` (each task in its own
+  checkout, with `path`, `base` and `setup`). Under `worktree`, a seat that isn't `mode: shared`
+  starts in the lobby — the parent of `workspace.path` with `.lobby` beside the worktrees, inside
+  `trust` and outside every protected checkout — never in the project root; `up` and `add` refuse a
+  seat whose folder, lobby included, would be protected or untrusted.
+
+The Codex profile is tested with CLI 0.157.0. Its status line is read for a weekly figure
+(`weekly N% left`) when the pane is wide enough to show the number; a cut line is not a figure.
+It adds `-a never -s danger-full-access`
+for unattended execution, plus `--no-daemon --no-alt-screen` for the captured pane mode,
+and checks login with `codex login status`. Rules go as a first message
+only at an empty idle prompt; delivery is recorded after Codex starts working with the input
+empty again. Nothing writes a vendor config or an `AGENTS.md`. `/exit` is sent only to a free
+seat. Update and workspace-trust screens are reported and closed without input; the owner
+handles them before relaunching. Other unrecognised layouts stay unknown.
+
+The Antigravity profile is tested with CLI 1.2.16 (`agy`). It adds `--dangerously-skip-permissions`
+for unattended execution, and checks authentication with `agy models`. Rules go as a first message
+only at an empty idle prompt; delivery is recorded after the CLI starts working with the composer
+empty again. Nothing writes a vendor config or an `AGENTS.md`. `/exit` is sent only to a free
+seat. Workspace-trust screens are reported and closed without input; the owner trusts the folder
+before relaunching. Other unrecognised layouts stay unknown.
+
+Launching a Cursor seat, like launching cursor-agent by hand, creates Cursor's own project record
+under ~/.cursor/projects for that folder; team writes no trust (.workspace-trusted) and no Cursor
+config.
+
+`budgets` is the owner's: marks (percent used), how long a figure stays fresh, and each
+account's reserve or floor. A `check` command is resolved to a file and hashed when the
+owner approves. A change to that file leaves that account's check unapproved: it is
+not run, and the account reads unknown, until the owner approves again. The rest of
+the file still runs. `watch.quota_marks` is still read, with a warning, until you move it to
+`budgets.marks`. A figure first seen on one seat does not count until it changes or a
+second seat shows the same number. It goes stale from the moment it last changed, and
+the last readings are kept in the state file beside the team file. `team status` prints
+them, one row per account and window, when there is an account or a stored reading.
+
+`examples/checks/codex-quota` is a check for an openai account. It ships with the package: with a
+global install it is at `$(npm root -g)/team/examples/checks/codex-quota`, and it is
+[examples/checks/codex-quota](https://github.com/floor/team/blob/main/examples/checks/codex-quota)
+in the repository. It is a Bun script — the check needs Bun on `PATH`, whatever runs `team` — and
+it uses only built-in file modules, so there is no package to install beside it. Copy it onto
+`PATH` and name that command:
+
+```yaml
+openai:
+  kind: subscription
+  reserve: 10%
+  sources: [check, status_line]
+  check: codex-quota
+```
+
+`team` runs a check with an empty environment plus `PATH` and `HOME`, so a
+`CODEX_HOME` set in the owner's shell never reaches the script. It reads
+`~/.codex/sessions`. When Codex's home is somewhere else, install a two-line
+wrapper and name the wrapper as the check:
+
+```sh
+#!/bin/sh
+CODEX_HOME=/path/to/codex exec /path/to/codex-quota
+```
+
+The wrapper sets `CODEX_HOME` and execs this script. The script takes rollouts
+newest first. The first that has a `token_count` primary window is the one used, and
+at most ten files are opened. A new session that has not recorded a figure yet
+does not hide the last one. The line's `at` is that event's own time, so an
+older figure stays dated. It prints the primary window, and a second line when
+that event's secondary window is a different length, such as
+`session 21% used resets 3h at 1791091200` and
+`weekly 39% used resets 114h4m at 1791091200`. The same length is not printed
+twice. A secondary figure that cannot be written is left off. When the primary
+figure cannot be written, nothing is printed. Five hours (`300` minutes) is
+`session`, a day (`1440`) is `daily`, and a week (`10080`) is `weekly`. Any other
+length, a figure over 100%, or no such rollout prints nothing, so the account
+reads unknown. `team approve` records the command you named. Bun has to be on
+`PATH` when the check runs.
+
+More fields exist — `tools`, `trust`, `machine`, `limits`, `watch`, `visibility` — and the comments
+`team init` writes name them; validation refuses what it cannot check, and this build acts on what
+the commands below read.
+
+## Commands
+
+| Command | What it does | Who may run it |
+| --- | --- | --- |
+| `team init` | writes the skeleton `.agents/team.yaml` and adds it and its runtime files to `.git/info/exclude` | the owner |
+| `team approve` | reads the whole file back for a last look, then records it, its ceilings and its seats on this machine; `--show` prints it | the owner (`--show`: anyone) |
+| `team check <ref>` | checks one commit, a `a..b` range, or a PR body (`--pr <file>`, `-` reads stdin) against the signature rule; exit 1 when one is refused | anyone; read only |
+| `team doctor` | checks this machine for what the file needs: herdr, each CLI, login, launcher, model, watch heartbeat; `--login` checks only CLI sign-ins | anyone; read only |
+| `team status` | prints the file's seats against the running session, each difference with its repair; `--json` outputs a stable JSON document (`format: 1`) for scripts; exit 1 when they differ | anyone; read only |
+| `team up` / `team down` | starts / stops the session and its seats | `up`: the owner; `down`: the owner, the coordinator or the operator seat |
+| `team watch` | watches the session, reports idle seats and nudges the operator; `--no-nudge` and `--no-notify` turn those off | anyone, one per session; it types only its fixed nudge, into an empty idle prompt |
+| `team add <name>` | starts one declared seat, or puts one back from the approved copy; `--temporary --like <seat> --until <end>` starts a seat the file does not hold | the owner, the coordinator or the operator |
+| `team remove <name>` | stops one seat, then takes it out of the file; `--keep` leaves it stopped; `--abandon` is the owner's, and types nothing | the owner, the coordinator or the operator; only the owner removes the coordinator or the operator |
+| `team worktree new <task>` / `team worktree remove <task>` | creates a task worktree from an up-to-date base, or removes its folder; a failed setup is kept and recorded; the branch is never deleted; ignored files in the worktree are deleted with it | the owner, the coordinator or the operator |
+
+Each command has its own page in [docs/commands](https://github.com/floor/team/tree/main/docs/commands): the synopsis, what it reads and
+writes, who may run it, every flag, the refusals with their exact text, the exit codes, and examples
+that `bun run ci` runs against a fixture team.
+
+The owner is a terminal outside herdr with no agent process above it: a seat, or a script a seat
+runs, cannot approve a file or start a team. Every command that reads the file also takes
+`--file <path>` for a file other than `.agents/team.yaml`.
+
+`team status --json` prints the facts `status` prints as one JSON document (`format: 1`) on stdout:
+`project`, `session`, `rows` (`name`, `state`, `model`, `pane`), `notes`, `differences` (`what`, `repair`), and `notice`.
+
+`team doctor --login` checks read-only that each CLI in the file is signed in, using each profile's
+existing login check command (`cursor-agent status`, `agy models`, `codex login status`, `claude auth status`).
+It never answers prompts and performs no sign-in action.
+
+`team up`, `team down`, `team add`, `team remove`, `team worktree new` and `team worktree remove`
+run live. `up` and `down` take `--dry-run` to print every command they would run, and every
+refusal, and change nothing. `trust` is specified but not built yet.
+
+## Your first team in five minutes
+
+```sh
+mkdir hello && cd hello && git init
+team init                  # the owner: writes .agents/team.yaml, private to this clone
+$EDITOR .agents/team.yaml  # name your seats — the example above is a working file
+team approve               # the owner: read the file it prints, then type the seat count
+team doctor                # what this machine still needs
+team up --dry-run          # every command it would run, and every refusal
+team up                    # the owner: starts the session and its seats
+```
+
+`team init` writes a skeleton, one seat and lots of comments; it prints how the file stays private,
+and leaves your first commit as a commented `#   since:` line. `team approve` prints the whole file
+back and asks you to type how many seats it holds, so no file approves itself unnoticed. Then
+`doctor` says what is missing on this machine, `up --dry-run` shows every command the launch would
+run — and `up` starts the team, from the owner's terminal outside herdr.
+
+## Development
+
+To run this tree's command from a clone instead of npm:
+
+```sh
+git clone https://github.com/floor/team.git
+cd team
+bun install
+bun run build
+npm install -g .          # puts `team` on the PATH
+team --version            # 0.1.0
+```
+
+Bun builds and tests the sources:
+
+```sh
+bun install
+bun run typecheck
+bun test
+bun run build        # dist/, which runs on Node 22 or later
+bun run ci           # what CI runs: typecheck, tests, build, then the built command's --version
+```
+
+Sources import each other with `.ts` extensions and use erasable syntax only, so Node can run them
+directly; `tsc` writes `dist/` for the published command. CI also runs `team check` on every pull
+request, against the team file the repository keeps at `.github/team.yaml`.
+
+### The end-to-end run
+
+`bun run e2e` drives the real commands — `status`, `watch` (one pass), `add --temporary --like`,
+`remove` and `down` — against fake seats, in a herdr session of its own (`team-test-e2e`) that it
+creates and always stops and deletes. A fake seat is `scripts/fake-seat.ts`: a pane that draws one
+of the screens the commands classify, logs every byte typed at it, and leaves on `/exit` and Enter.
+No model runs and nothing reaches the network. After each command the run checks its exit code, its
+own output, the log lines it wrote to `.agents/team.log`, and the seat records in
+`.agents/team.state.json`.
+
+It is local only: CI has no herdr, so `bun run ci` does not run it. It refuses to start when herdr
+is not on the PATH, when the machine is over its gate (load under 60, 25 % memory free, swap not
+growing over a minute), or when a session named `team-test-e2e` already exists. It works in a fresh
+folder under the system's temporary directory — the project, the approval store and the fake seats'
+input logs — and prints that path; it never writes the owner's home. It reads the default herdr
+session's agent list before and after, and fails when the count changes.
+
+Every check prints a line; the run ends with `all N checks passed` or `M of N checks failed` and
+exits 2 when it refused to start, 1 when a check failed. A failed step skips the steps after it,
+and the session is stopped and deleted on every path.
+
+## Releasing
+
+The owner cuts a release by pushing a version tag: `git tag v0.2.0 && git push origin v0.2.0`. The
+Release workflow (`.github/workflows/release.yml`) refuses a tag that isn't `package.json`'s
+version or whose commit isn't on `main`, runs `bun run ci`, then publishes with npm trusted
+publishing — the workflow's own identity, no token stored — and provenance. A version with a
+hyphen (`0.2.0-next.1`) goes under the `next` dist-tag, any other under `latest`. Once npm has the
+version, the same run creates the GitHub release from the `CHANGELOG.md` section for it, marked a
+pre-release when the version is one. If the GitHub release step fails — a missing changelog
+section, say — use "Re-run failed jobs": a full re-run goes back through `npm publish`, which
+fails because that version is already on npm. A tag ruleset protecting `v*`, so that only the
+owner creates version tags, is recommended.
+
+Trusted publishing must be bound once, by the package owner, on npmjs.com: the package `team` →
+Publishing → trusted publishers → GitHub Actions, naming `floor/team` and the workflow file
+`release.yml`; until then the workflow cannot publish. The 0.1.0 release itself is a manual
+`npm publish` from a clean `main`; the workflow covers the releases after it.
+
+## License
+
+MIT

package/dist/approve/approval.d.ts

@@ -0,0 +1,38 @@
+import type { ApprovedCheck } from '../budgets/checks.ts';
+import type { TeamFile } from '../file/types.ts';
+import { type Approval, type ApprovalRecord, type Ceilings } from '../store/store.ts';
+import { type Fingerprints } from './fingerprint.ts';
+/** The ceilings an approval fixes: `up` and `add` read them from the record, never from the file. */
+export declare function ceilingsOf(team: TeamFile): Ceilings;
+/** The record an approval of this file writes. */
+export declare function approvalOf(team: TeamFile, root: string, now?: Date, checks?: Record<string, ApprovedCheck>): Approval;
+/**
+ * An approval's fingerprints, with the sections a record written before them has none for read
+ * from the copy it stored: `watch` and `watch.checks` arrived after records did, and the section's
+ * arrival alone is not a difference — an approval recorded before it stays valid while the section
+ * is unchanged (as `watch.checks` has since #48). A copy that can't be read leaves the record as
+ * it is, and the section reads as a difference.
+ */
+export declare function approvedFingerprints(record: ApprovalRecord): Fingerprints;
+/**
+ * What in the file the owner has not approved on this machine, one line per
+ * difference. Empty when the file is the approved one; null when nothing was
+ * ever approved for this root. A file runs only when this is empty.
+ */
+export declare function approvalDifferences(team: TeamFile, root: string, home?: string): string[] | null;
+/**
+ * The watch values in force. The watch section is the owner's, so what a file sets takes effect
+ * only once the owner has approved it: a file never approved runs with the defaults, and a file
+ * whose `watch` section differs from the approved one runs with the values of the approved copy.
+ * An edit to a threshold changes nothing until `approve`.
+ */
+export declare function watchInForce(team: TeamFile, root: string, home?: string): TeamFile['watch'];
+/**
+ * The budget values in force. The `budgets` section is the owner's like the watch's, so what a
+ * file sets takes effect only once the owner has approved it: a file never approved runs with the
+ * defaults — no accounts — and a file whose `budgets` section differs from the approved one runs
+ * with the values of the approved copy, accounts included. An unapproved edit — a reserve lowered,
+ * a mark dropped, `check_every` stretched, an account taken out — silences nothing and unblocks
+ * nothing until `approve`.
+ */
+export declare function budgetsInForce(team: TeamFile, root: string, home?: string): TeamFile['budgets'];

package/dist/approve/approval.js

@@ -0,0 +1,78 @@
+import { homedir } from 'node:os';
+import { defaultBudgets, defaultWatch, validateTeamFile } from "../file/validate.js";
+import { readApproval, storePath } from "../store/store.js";
+import { compare, describe, fingerprints, OWNER_SECTIONS } from "./fingerprint.js";
+/** The ceilings an approval fixes: `up` and `add` read them from the record, never from the file. */
+export function ceilingsOf(team) {
+    return { seats: team.limits.seats, temporary: team.limits.temporary, vendors: { ...team.limits.vendors } };
+}
+/** The record an approval of this file writes. */
+export function approvalOf(team, root, now = new Date(), checks = {}) {
+    return {
+        format: 1,
+        approvedAt: now.toISOString(),
+        root,
+        fingerprints: fingerprints(team),
+        ceilings: ceilingsOf(team),
+        checks,
+    };
+}
+/**
+ * An approval's fingerprints, with the sections a record written before them has none for read
+ * from the copy it stored: `watch` and `watch.checks` arrived after records did, and the section's
+ * arrival alone is not a difference — an approval recorded before it stays valid while the section
+ * is unchanged (as `watch.checks` has since #48). A copy that can't be read leaves the record as
+ * it is, and the section reads as a difference.
+ */
+export function approvedFingerprints(record) {
+    const stored = record.approval.fingerprints;
+    if (OWNER_SECTIONS.every((name) => stored.sections[name] !== undefined))
+        return stored;
+    const checked = validateTeamFile(record.file);
+    if (!checked.ok)
+        return stored;
+    return { sections: { ...fingerprints(checked.team).sections, ...stored.sections }, seats: stored.seats };
+}
+/**
+ * What in the file the owner has not approved on this machine, one line per
+ * difference. Empty when the file is the approved one; null when nothing was
+ * ever approved for this root. A file runs only when this is empty.
+ */
+export function approvalDifferences(team, root, home = homedir()) {
+    const record = readApproval(storePath(team.project, root, home));
+    if (record === null)
+        return null;
+    return compare(approvedFingerprints(record), fingerprints(team)).map(describe);
+}
+/**
+ * The watch values in force. The watch section is the owner's, so what a file sets takes effect
+ * only once the owner has approved it: a file never approved runs with the defaults, and a file
+ * whose `watch` section differs from the approved one runs with the values of the approved copy.
+ * An edit to a threshold changes nothing until `approve`.
+ */
+export function watchInForce(team, root, home = homedir()) {
+    const record = readApproval(storePath(team.project, root, home));
+    if (record === null)
+        return defaultWatch();
+    if (approvedFingerprints(record).sections['watch'] === fingerprints(team).sections['watch'])
+        return team.watch;
+    const copy = validateTeamFile(record.file);
+    return copy.ok ? copy.team.watch : defaultWatch();
+}
+/**
+ * The budget values in force. The `budgets` section is the owner's like the watch's, so what a
+ * file sets takes effect only once the owner has approved it: a file never approved runs with the
+ * defaults — no accounts — and a file whose `budgets` section differs from the approved one runs
+ * with the values of the approved copy, accounts included. An unapproved edit — a reserve lowered,
+ * a mark dropped, `check_every` stretched, an account taken out — silences nothing and unblocks
+ * nothing until `approve`.
+ */
+export function budgetsInForce(team, root, home = homedir()) {
+    const record = readApproval(storePath(team.project, root, home));
+    if (record === null)
+        return defaultBudgets();
+    if (approvedFingerprints(record).sections['budgets'] === fingerprints(team).sections['budgets'])
+        return team.budgets;
+    const copy = validateTeamFile(record.file);
+    return copy.ok ? copy.team.budgets : defaultBudgets();
+}

package/dist/approve/diff.d.ts

@@ -0,0 +1,13 @@
+/** One line of a comparison: kept, taken out of the old text, or added by the new one. */
+export type DiffLine = {
+    kind: 'same' | 'removed' | 'added';
+    text: string;
+    line: number;
+};
+/**
+ * The lines of `after` against `before`, by their longest common subsequence.
+ * `line` is the line's number in the text it comes from.
+ */
+export declare function diffLines(before: string, after: string): DiffLine[];
+/** The changed lines only, as `- 12: old` and `+ 12: new`; empty when the texts are equal. */
+export declare function formatDiff(before: string, after: string): string[];

package/dist/approve/diff.js

@@ -0,0 +1,47 @@
+/**
+ * The lines of `after` against `before`, by their longest common subsequence.
+ * `line` is the line's number in the text it comes from.
+ */
+export function diffLines(before, after) {
+    const a = before.split('\n');
+    const b = after.split('\n');
+    // lengths[i][j]: the longest common subsequence of a[i..] and b[j..].
+    const lengths = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--) {
+            lengths[i][j] =
+                a[i] === b[j]
+                    ? lengths[i + 1][j + 1] + 1
+                    : Math.max(lengths[i + 1][j], lengths[i][j + 1]);
+        }
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j]) {
+            out.push({ kind: 'same', text: b[j], line: j + 1 });
+            i++;
+            j++;
+        }
+        else if (lengths[i + 1][j] >= lengths[i][j + 1]) {
+            out.push({ kind: 'removed', text: a[i], line: i + 1 });
+            i++;
+        }
+        else {
+            out.push({ kind: 'added', text: b[j], line: j + 1 });
+            j++;
+        }
+    }
+    for (; i < a.length; i++)
+        out.push({ kind: 'removed', text: a[i], line: i + 1 });
+    for (; j < b.length; j++)
+        out.push({ kind: 'added', text: b[j], line: j + 1 });
+    return out;
+}
+/** The changed lines only, as `- 12: old` and `+ 12: new`; empty when the texts are equal. */
+export function formatDiff(before, after) {
+    return diffLines(before, after)
+        .filter((line) => line.kind !== 'same')
+        .map((line) => `${line.kind === 'removed' ? '-' : '+'} ${line.line}: ${line.text}`);
+}

package/dist/approve/fingerprint.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The sections only the owner changes. An edit to any of them needs a new
+ * approval before the file runs.
+ */
+export declare const OWNER_SECTIONS: readonly ["trust", "limits", "machine", "rules", "identity", "workspace", "coordinator", "operator", "session", "visibility", "tools", "budgets", "watch", "watch.checks"];
+/** A validated team file, as far as an approval reads it. */
+export type Approvable = Record<string, unknown> & {
+    seats: readonly (Record<string, unknown> & {
+        name: string;
+    })[];
+};
+export interface Fingerprints {
+    sections: Record<string, string>;
+    /** By seat name, after `count` is expanded. */
+    seats: Record<string, string>;
+}
+/** JSON with every object's keys in order, so equal values give equal text. */
+export declare function canonical(value: unknown): string;
+/** A fingerprint of each owner-only section and of each seat. */
+export declare function fingerprints(team: Approvable): Fingerprints;
+export type Difference = {
+    kind: 'section';
+    name: string;
+} | {
+    kind: 'seat-changed';
+    name: string;
+} | {
+    kind: 'seat-new';
+    name: string;
+};
+/**
+ * What in the file the owner has not approved. The file passes when every
+ * section matches and every seat in it matches an approved seat: a seat taken
+ * out, parked or stopped needs no new approval.
+ */
+export declare function compare(approved: Fingerprints, current: Fingerprints): Difference[];
+/**
+ * The line `describe` prints when `watch.checks` itself is the difference. `pass` reads it to
+ * keep the checks running until the owner approves an edit that would turn one off: nothing is
+ * turned off until the owner approves (RFC 0002 § 4.2).
+ */
+export declare const WATCH_CHECKS_CHANGED = "`watch.checks` changed";
+/** One line per difference, as `status`, `doctor` and the refusals print it. */
+export declare function describe(difference: Difference): string;

package/dist/approve/fingerprint.js

@@ -0,0 +1,109 @@
+import { createHash } from 'node:crypto';
+/**
+ * The sections only the owner changes. An edit to any of them needs a new
+ * approval before the file runs.
+ */
+export const OWNER_SECTIONS = [
+    'trust',
+    'limits',
+    'machine',
+    'rules',
+    'identity',
+    'workspace',
+    'coordinator',
+    'operator',
+    'session',
+    'visibility',
+    'tools',
+    'budgets',
+    // The watch's own timings, thresholds included: a seat allowed to stretch `unsent_after` or
+    // `idle_first` could silence the watch itself, so the section is the owner's like the rest.
+    'watch',
+    // And turning a check off is the finer line inside it: the digest above leaves the checks out,
+    // so turning one off reads as `watch.checks` alone, never as a threshold change too.
+    'watch.checks',
+];
+/** One owner section, read from the file; the two watch sections sit inside `watch`, not at the top. */
+function sectionOf(team, name) {
+    if (name === 'watch.checks')
+        return team.watch?.checks ?? [];
+    if (name === 'watch') {
+        const watch = team.watch;
+        if (watch === null || watch === undefined)
+            return undefined;
+        const rest = { ...watch };
+        delete rest.checks;
+        return rest;
+    }
+    return team[name];
+}
+/**
+ * Seat fields that change without a new approval: what `remove --keep` and
+ * `add` set, where the seat sits in the file, and how its entry is written
+ * (`count: 3` becoming `count: 2`, or explicit seats, when one is taken out).
+ */
+const SEAT_FREE_FIELDS = new Set(['parked', 'stopped', 'line', 'declared', 'count', 'instance']);
+/** JSON with every object's keys in order, so equal values give equal text. */
+export function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonical(item ?? null)).join(',')}]`;
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(',')}}`;
+    }
+    return JSON.stringify(value ?? null);
+}
+function digest(value) {
+    return createHash('sha256').update(canonical(value)).digest('hex');
+}
+/** A fingerprint of each owner-only section and of each seat. */
+export function fingerprints(team) {
+    const sections = {};
+    for (const section of OWNER_SECTIONS)
+        sections[section] = digest(sectionOf(team, section));
+    const seats = {};
+    for (const seat of team.seats) {
+        const fields = Object.fromEntries(Object.entries(seat).filter(([key]) => !SEAT_FREE_FIELDS.has(key)));
+        seats[seat.name] = digest(fields);
+    }
+    return { sections, seats };
+}
+/**
+ * What in the file the owner has not approved. The file passes when every
+ * section matches and every seat in it matches an approved seat: a seat taken
+ * out, parked or stopped needs no new approval.
+ */
+export function compare(approved, current) {
+    const differences = [];
+    for (const name of OWNER_SECTIONS) {
+        // A record with no fingerprint for a section is read by `approvedFingerprints`, from the copy
+        // it stored. What reaches here without one is a record whose copy is gone: it turned nothing
+        // off, so `watch.checks` reads as the empty list, and a missing `watch` is a difference.
+        const before = approved.sections[name] ?? (name === 'watch.checks' ? digest([]) : undefined);
+        if (before !== current.sections[name])
+            differences.push({ kind: 'section', name });
+    }
+    for (const [name, fingerprint] of Object.entries(current.seats)) {
+        if (!Object.hasOwn(approved.seats, name))
+            differences.push({ kind: 'seat-new', name });
+        else if (approved.seats[name] !== fingerprint)
+            differences.push({ kind: 'seat-changed', name });
+    }
+    return differences;
+}
+/**
+ * The line `describe` prints when `watch.checks` itself is the difference. `pass` reads it to
+ * keep the checks running until the owner approves an edit that would turn one off: nothing is
+ * turned off until the owner approves (RFC 0002 § 4.2).
+ */
+export const WATCH_CHECKS_CHANGED = '`watch.checks` changed';
+/** One line per difference, as `status`, `doctor` and the refusals print it. */
+export function describe(difference) {
+    if (difference.kind === 'section')
+        return `\`${difference.name}\` changed`;
+    if (difference.kind === 'seat-new')
+        return `seat ${difference.name} is not in the approved file`;
+    return `seat ${difference.name} changed`;
+}