@manyoars/oars 0.4.0 → 0.5.1

package/dist/cli.js

@@ -7,16 +7,24 @@ import { logout } from './commands/logout.js';
 import { CliError, ExitCode } from './errors.js';
 import { closedQueryOf, formsRefusal, RECALL_FAMILIES } from './sessions/recall-reads.js';
 import { FAMILIES } from './sessions/read.js';
-import { sessionsBooks, sessionsContext, sessionsDeposit, sessionsGoldArms, sessionsGoldSample, sessionsGoldScore, sessionsHookInstall, sessionsHookStatus, sessionsHookUninstall, sessionsMcp, sessionsLineage, sessionsMeasure, sessionsRead, sessionsRecall, sessionsRecallCounts, sessionsVerify } from './sessions/command.js';
+import { sessionsBooks, sessionsContext, sessionsDeposit, sessionsGoldArms, sessionsGoldSample, sessionsGoldScore, sessionsHookInstall, sessionsHookStatus, sessionsHookUninstall, sessionsMcp, sessionsLineage, sessionsMeasure, sessionsRead, sessionsRecall, sessionsReceipt, sessionsRecallCounts, sessionsVerify } from './sessions/command.js';
+import { sessionsCard } from './sessions/card-command.js';
 import { gateInstall, gatePolicy, gateReplay, gateReport, gateUninstall } from './gate/command.js';
 import { DEADLINE_MS, gateHook } from './gate/hook.js';
 import { managerReader } from './gate/registry.js';
 import { exclusionPaths, sessionsExclusions } from './sessions/exclusion.js';
-import { poolCoverage, poolDeposit, poolFetch, poolLogin, poolOutbox, poolRaw } from './sessions/pool-command.js';
+import { sessionsTry } from './sessions/try.js';
+import { board, clubCreate, clubJoin, clubLeave, clubShow } from './club.js';
+import { githubVisibility, poolEnroll, poolMachineRevoke, poolMachines } from './sessions/machine-enroll.js';
+import { runNetGit } from './sessions/machine-hold.js';
+import { holdPull } from './sessions/machine-pull.js';
+import { runGit } from './sessions/survival.js';
+import { poolCoverage, poolDeposit, poolExport, poolFetch, poolLogin, poolLogout, poolOutbox, poolProve, poolRaw } from './sessions/pool-command.js';
 import { telemetryOff, telemetryOn, telemetryReport, telemetryShow, telemetryStatus } from './telemetry/command.js';
+import { cardLine } from './sessions/card-line.js';
 import { recordCrash } from './telemetry/crash.js';
 import { emitOf } from './telemetry/emit.js';
-import { finishTelemetry, observeCommand } from './telemetry/observe.js';
+import { finishTelemetry, isHook, observeCommand } from './telemetry/observe.js';
 const flag = (options, name) => options[name] === true;
 const text = (options, name) => {
     const value = options[name];
@@ -129,6 +137,20 @@ const buildProgram = (deps, observed) => {
         const options = command.optsWithGlobals();
         emit(deps, flag(options, 'json'), await keysRevoke(deps, { apiUrl: resolveApiUrl(deps, text(options, 'apiUrl')), keyId }));
     });
+    program
+        .command('card')
+        .description('a share-ready card of your own week, month, or year across every harness, read from your local store only: nothing is uploaded and no folder, path, prompt text, or private name is printed')
+        .option('--week', 'the last 7 days (the default)')
+        .option('--month', 'the last 30 days')
+        .option('--year', 'the last 365 days')
+        .option('--text', 'print the card as a table instead of saving a picture')
+        .option('--out <file>', 'save the card here, as .png or .svg: both are written, one with each extension (default oars-card-<period> in the working directory)')
+        .option('--no-cost', 'leave the cost row out of the picture, the table, and --json')
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        const period = flag(options, 'year') ? 'year' : flag(options, 'month') ? 'month' : 'week';
+        emit(deps, flag(options, 'json'), await sessionsCard(sessionDeps(deps), { period, text: flag(options, 'text'), out: text(options, 'out'), noCost: options.cost === false }, deps.env));
+    });
     const sessions = program.command('sessions').description("deposit and recall your own coding-agent session logs, locally (these commands make no model call and no network call, except `gold arms`, which asks your own Claude subscription; telemetry is separate: oars telemetry)");
     sessions
         .command('deposit')
@@ -141,6 +163,16 @@ const buildProgram = (deps, observed) => {
         const options = command.optsWithGlobals();
         emit(deps, flag(options, 'json'), await sessionsDeposit(sessionDeps(deps), { allow: list(options, 'allow'), allowFiles: list(options, 'allowFile'), deny: list(options, 'deny'), redactDomains: list(options, 'redactDomain') }));
     });
+    sessions
+        .command('try')
+        .description('see recall, books, and the hook line work on made-up sessions, with no history of your own: it builds a throwaway store under your temp folder, labels everything it prints as synthetic, and deletes the store when it exits. It never reads or writes your real store')
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        // The command promises no network call: drop the sender before it runs, so the daily telemetry send that follows every command cannot start one, whether the run returns or throws.
+        if (deps.telemetry !== undefined)
+            deps.telemetry = { dir: deps.telemetry.dir, platform: deps.telemetry.platform };
+        emit(deps, flag(options, 'json'), await sessionsTry(deps));
+    });
     sessions
         .command('recall')
         .description('look a tool error, a file, or a prompt class up in the store (--mcp serves the same query to a running agent). Note: an error pasted with a leading <tool_use_error> line does not match a stored signature, because the extractor keeps that markup line as the signature (reference-script behavior); paste the line below it')
@@ -153,7 +185,8 @@ const buildProgram = (deps, observed) => {
         .option('--family <name>', `one read family (${RECALL_FAMILIES.join(', ')}); only recovery and fit are narrowed by --class and --since`)
         .option('--text <text>', 'look for text in the local record')
         .option('--session <id>', 'the session asking, so what it did next can be read for this recall')
-        .option('--counts', 'print counts of recalls by mode, arm, and answer, with what followed, instead of answering (see --day)')
+        .option('--receipt', 'with --error: print a redacted Markdown block to paste into an issue on the failing tool (tool, harness, normalized signature, earlier sessions and weeks, what they did next)')
+        .option('--counts', 'print counts of recalls by mode, arm, and answer, with how many windows hold a call named like a shown action, instead of answering (see --day)')
         .option('--day <yyyy-mm-dd>', 'with --counts: only this UTC day')
         .option('--mcp', 'serve one recall tool over MCP on stdio instead of answering once')
         .option('--context', "print the repository's top recurring errors as a short block for injection into a session (see --cwd, --harness, --top, --max-chars)")
@@ -163,6 +196,12 @@ const buildProgram = (deps, observed) => {
         .option('--max-chars <n>', "with --context: the block's length limit (default 1200)", positiveInteger)
         .action(async (_options, command) => {
         const options = command.optsWithGlobals();
+        if (flag(options, 'receipt')) {
+            if (flag(options, 'counts') || flag(options, 'mcp') || flag(options, 'context') || list(options, 'pattern').length > 0 || text(options, 'entity') !== undefined || text(options, 'family') !== undefined || text(options, 'text') !== undefined)
+                throw new CliError('--receipt answers one error: pass --error "<text>" and no other form.', ExitCode.USAGE, 'usage');
+            emit(deps, flag(options, 'json'), await sessionsReceipt(sessionDeps(deps), { ...(text(options, 'error') === undefined ? {} : { error: text(options, 'error') }), ...(text(options, 'path') === undefined ? {} : { path: text(options, 'path') }), ...(text(options, 'class') === undefined ? {} : { cls: text(options, 'class') }), ...(count(options, 'since') === undefined ? {} : { sinceDays: count(options, 'since') }) }, text(options, 'session') ?? null));
+            return;
+        }
         if (flag(options, 'counts')) {
             emit(deps, flag(options, 'json'), await sessionsRecallCounts(sessionDeps(deps), text(options, 'day')));
             return;
@@ -310,7 +349,7 @@ const buildProgram = (deps, observed) => {
         const options = command.optsWithGlobals();
         emit(deps, flag(options, 'json'), await sessionsGoldArms(sessionDeps(deps), { file }));
     });
-    const hook = sessions.command('hook').description('install the recall hooks into a Claude Code settings file, and the nightly deposit task');
+    const hook = sessions.command('hook').description('install the recall hooks into a Claude Code settings file, and remove the scheduled task earlier versions registered');
     const scopeOption = (value) => {
         if (value !== 'user' && value !== 'project' && value !== 'file')
             throw new InvalidArgumentError('it must be user, project, or file.');
@@ -320,15 +359,25 @@ const buildProgram = (deps, observed) => {
         const value = text(options, 'scope');
         return value === 'user' || value === 'project' || value === 'file' ? value : undefined;
     };
+    const harnessOption = (value) => {
+        if (value !== 'codex')
+            throw new InvalidArgumentError('it must be codex (Claude Code is the default and needs no flag).');
+        return value;
+    };
+    const harnessOf = (options) => (text(options, 'harness') === 'codex' ? 'codex' : undefined);
     hook
         .command('install')
-        .description('merge the SessionStart, UserPromptSubmit, PreToolUse, PostToolUseFailure, and SessionEnd hooks into a settings file (existing hooks are kept), raise cleanupPeriodDays to at least 365, and on Windows register the nightly task (which sends telemetry while telemetry is on, and pool batches only after you accept a pool covenant)')
+        .description('merge the SessionStart, UserPromptSubmit, PreToolUse, PostToolUseFailure, and SessionEnd hooks into a settings file (existing hooks are kept), raise cleanupPeriodDays to at least 365, and, on Windows, remove the nightly task an earlier version registered (oars installs no scheduler: a due sweep and send, at most about hourly, starts from the session-end hook and from any oars command; telemetry goes only while it is on, and pool batches only after you accept a pool covenant)')
         .option('--scope <scope>', 'user (~/.claude/settings.json; the default), project (./.claude/settings.json), or file (needs --file; implied by --file)', scopeOption)
         .option('--file <path>', 'the settings file for --scope file')
+        .option('--harness <harness>', 'codex: install the opt-in Codex recording hook in hooks.json in the Codex home instead (Codex asks you to trust it before it runs; it records tool and token rows locally while codex is allowed)', harnessOption)
         .option('--keep-retention', 'leave cleanupPeriodDays as it is (the harness deletes raw transcripts older than it)')
-        .option('--schedule <mode>', 'nightly: register a Windows task that runs the full deposit and the recurrence refresh daily (a plain install on Windows does this too); off: remove it', (value) => {
-        if (value !== 'nightly' && value !== 'off')
-            throw new InvalidArgumentError('it must be nightly or off.');
+        .option('--machine', 'write the Stop and SessionEnd entries of a machine (a cloud VM, a VPS, or a runner): they run oars-hook, which builds the batch of its session at each Stop only where OARS_HOST_CLASS names a class other than local; --scope project (committed) or --scope user')
+        .option('--env <name=value>', 'with --machine --scope user: one variable of the enrollment block for the env block of that file (OARS_HOST_CLASS is required; repeat the flag; OARS_EXCLUSION_TERMS_INLINE: one term per line; a comma is part of the term); the file is then made owner-only', (value, before) => [...(before ?? []), value])
+        .option('--terms-file <path>', 'with --machine --scope user: write the OARS_EXCLUSION_TERMS_INLINE terms to this owner-only file and name it in OARS_EXCLUSION_TERMS, so the settings file holds no term')
+        .option('--schedule <mode>', 'off: no background sweep or pool send from the session-end hook or from commands (telemetry has its own switch: oars telemetry off), and remove the task an earlier version registered; on: clear that choice; nightly is refused, because sends now ride the hook and commands', (value) => {
+        if (value !== 'nightly' && value !== 'off' && value !== 'on')
+            throw new InvalidArgumentError('it must be off or on (nightly is no longer registered).');
         return value;
     })
         .action(async (_options, command) => {
@@ -338,25 +387,31 @@ const buildProgram = (deps, observed) => {
             scope: scopeOf(options),
             file: text(options, 'file'),
             keepRetention: flag(options, 'keepRetention'),
-            schedule: schedule === 'nightly' || schedule === 'off' ? schedule : undefined,
+            schedule: schedule === 'nightly' || schedule === 'off' || schedule === 'on' ? schedule : undefined,
+            harness: harnessOf(options),
+            machine: flag(options, 'machine'),
+            env: list(options, 'env'),
+            termsFile: text(options, 'termsFile'),
         }));
     });
     hook
         .command('uninstall')
-        .description('remove only the hooks `install` wrote from a settings file (cleanupPeriodDays stays; `install --schedule off` removes the task)')
+        .description('remove only the hooks `install` wrote from a settings file (cleanupPeriodDays stays; it also removes the task an earlier version registered)')
         .option('--scope <scope>', 'user (the default), project, or file (needs --file; implied by --file)', scopeOption)
         .option('--file <path>', 'the settings file for --scope file')
+        .option('--harness <harness>', 'codex: remove only the Codex recording hook from hooks.json in the Codex home', harnessOption)
         .action(async (_options, command) => {
         const options = command.optsWithGlobals();
-        emit(deps, flag(options, 'json'), await sessionsHookUninstall(sessionDeps(deps), { scope: scopeOf(options), file: text(options, 'file') }));
+        emit(deps, flag(options, 'json'), await sessionsHookUninstall(sessionDeps(deps), { scope: scopeOf(options), file: text(options, 'file'), harness: harnessOf(options) }));
     });
     hook
         .command('status')
-        .description('what is installed in the user and project settings (and --file), and whether the nightly task is registered')
+        .description('what is installed in the user and project settings (and --file), and whether a task an earlier version registered is still there')
         .option('--file <path>', 'one more settings file to report')
+        .option('--harness <harness>', 'codex: report the Codex recording hook in hooks.json in the Codex home instead', harnessOption)
         .action(async (_options, command) => {
         const options = command.optsWithGlobals();
-        emit(deps, flag(options, 'json'), await sessionsHookStatus(sessionDeps(deps), { file: text(options, 'file') }));
+        emit(deps, flag(options, 'json'), await sessionsHookStatus(sessionDeps(deps), { file: text(options, 'file'), harness: harnessOf(options) }));
     });
     const gate = program.command('gate').description('record the install, fetch-and-run, MCP, and skill picks your agents make, live through a hook or from logs already on disk, without judging them');
     gate
@@ -407,27 +462,81 @@ const buildProgram = (deps, observed) => {
         .action(async (_options, command) => {
         emit(deps, flag(command.optsWithGlobals(), 'json'), await gateReport(sessionDeps(deps)));
     });
-    const pool = program.command('pool').description('sign in to a pool server, deposit session skeletons (a closed list of fields, each value redacted first) and, after a yes to the raw prompt, redacted raw copies, and fetch signed reads; local capture, recall, and reads need none of it');
+    const pool = program.command('pool').description('sign in to a pool server, deposit session skeletons (a closed list of fields, each value redacted first) and, after a yes to the raw prompt, redacted raw copies, and fetch signed reads; local capture, recall, and reads need none of it. The covenant screen, where you type its phrase to accept, appears when you send a batch with oars pool deposit --send <hash> and have not accepted the covenant in force, not at sign-in');
     const serverOption = '--server <url>';
     const serverHelp = 'the pool server, https or plain http to localhost (default: OARS_POOL_URL, else https://pool.manyoars.com)';
+    pool
+        .command('logout')
+        .description('revoke the credential held for this pool and remove it here; if the pool cannot be reached the local entry is still removed')
+        .option(serverOption, serverHelp)
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await poolLogout(deps, { server: text(options, 'server') }));
+    });
     pool
         .command('login')
-        .description('sign in by GitHub or Google device flow, run here against the provider; prints each request before sending it, and the pool keeps a pseudonym; no harness token is read')
+        .description('sign in by GitHub or Google device flow, run here against the provider; --verbose prints each request before sending it, and the pool keeps a pseudonym; no harness token is read')
         .requiredOption('--provider <name>', 'github or google')
+        .option('--verbose', 'print each request, headers and body, to stderr before it is sent (a credential shows as its size)')
+        .option(serverOption, serverHelp)
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await poolLogin(deps, { server: text(options, 'server'), provider: text(options, 'provider'), verbose: flag(options, 'verbose') }));
+    });
+    pool
+        .command('enroll')
+        .description('enroll a machine: print the whole configuration a cloud VM needs (host class, launcher, a new machine id, the repositories, two salts derived from this machine\'s, and your exclusion terms) after checking that each repository is private (GH_TOKEN or GITHUB_TOKEN lets the check see a private one). With --hold-only that is all, and no pool credential is used; without it the pool also issues a one-time enrollment token for the machine, which needs oars pool login')
+        .option('--hold-only', 'hold in the session\'s own repository and send nothing to the pool: no login, no token')
+        .option('--host-class <class>', 'vps, cloud, ci, or hosted')
+        .option('--launcher <launcher>', 'interactive, orchestrated, or scheduled')
+        .option('--allow-repos <repos>', 'the repositories the machine may hold, as owner/name; repeat the flag or separate them with commas', collect)
+        .option('--name <label>', 'without --hold-only: the label the pool lists this machine by (letters, digits, spaces, dots, underscores, and hyphens; 64 at most)')
+        .option('--days <n>', 'without --hold-only: how many days the machine\'s key lives from its activation, 1 to 365 (default 90)')
+        .option(serverOption, serverHelp)
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        const token = deps.env.GH_TOKEN ?? deps.env.GITHUB_TOKEN;
+        emit(deps, flag(options, 'json'), await poolEnroll(deps, { holdOnly: flag(options, 'holdOnly'), hostClass: text(options, 'hostClass'), launcher: text(options, 'launcher'), allowRepos: list(options, 'allowRepos'), name: text(options, 'name'), days: text(options, 'days'), server: text(options, 'server') }, githubVisibility(fetch, token)));
+    });
+    const machines = pool
+        .command('machines')
+        .description('list the machines enrolled with the pool: label, id, host class, launcher, state, last deposit day, and expiry; needs oars pool login')
+        .option(serverOption, serverHelp)
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await poolMachines(deps, { server: text(options, 'server') }));
+    });
+    machines
+        .command('revoke')
+        .argument('<id>', 'the machine\'s id, as oars pool machines lists it')
+        .description('revoke one machine: its key is refused from its next request')
+        .option(serverOption, serverHelp)
+        .action(async (id, _options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await poolMachineRevoke(deps, id, { server: text(options, 'server') }));
+    });
+    pool
+        .command('hold')
+        .description('the trusted machine\'s side of the holding route')
+        .command('pull')
+        .description('on the trusted machine, read the oars-hold/* branch tips of every enrolled machine\'s private repositories (each repository\'s visibility is checked again on every run) and admit each batch that passes every gate to the outbox; a branch that does not is reported and left where it is. Uses this machine\'s own git credential and GH_TOKEN or GITHUB_TOKEN for the visibility check')
         .option(serverOption, serverHelp)
         .action(async (_options, command) => {
         const options = command.optsWithGlobals();
-        emit(deps, flag(options, 'json'), await poolLogin(deps, { server: text(options, 'server'), provider: text(options, 'provider') }));
+        const token = deps.env.GH_TOKEN ?? deps.env.GITHUB_TOKEN;
+        const ports = { visibility: githubVisibility(fetch, token), git: runGit, net: runNetGit, remoteOf: (repo) => `https://github.com/${repo}.git` };
+        emit(deps, flag(options, 'json'), await holdPull(deps, { server: text(options, 'server') }, ports));
     });
     pool
         .command('deposit')
-        .description('write a batch to the outbox for each session that passes the folder allowlist and the exclusion check, and stop: nothing is sent, and only counts print. --send <hash> sends one batch that oars pool outbox printed and that is unchanged, once this account has accepted the pool covenant')
-        .option('--accept-covenant <version>', 'accept this version of the pool covenant before sending (with --send)')
+        .description('write a batch to the outbox for each session that passes the folder allowlist and the exclusion check, and stop: no session data is sent, and only counts print. --send <hash> sends one batch that oars pool outbox printed and that is unchanged, once this account has accepted the pool covenant')
+        .option('--accept-covenant <version>', 'name the covenant version you expect, with --send: on a terminal the screen is shown and you type its phrase yourself, and off a terminal this is refused')
+        .option('--in-eu-eea-uk <yes|no>', 'answer "Are you in the EU, the EEA, or the UK?" when you accept, with --send; without it a person is asked, with or without --accept-covenant. While the pool is closed to those regions, yes is refused')
         .option('--send <hash>', 'the SHA-256 of a batch that oars pool outbox printed')
         .option(serverOption, serverHelp)
         .action(async (_options, command) => {
         const options = command.optsWithGlobals();
-        emit(deps, flag(options, 'json'), await poolDeposit(deps, { server: text(options, 'server'), acceptCovenant: text(options, 'acceptCovenant'), send: text(options, 'send') }));
+        emit(deps, flag(options, 'json'), await poolDeposit(deps, { server: text(options, 'server'), acceptCovenant: text(options, 'acceptCovenant'), inEuEeaUk: text(options, 'inEuEeaUk'), send: text(options, 'send') }));
     });
     pool
         .command('raw')
@@ -457,6 +566,24 @@ const buildProgram = (deps, observed) => {
         const options = command.optsWithGlobals();
         emit(deps, flag(options, 'json'), await poolOutbox(deps, { server: text(options, 'server'), explain: flag(options, 'explain') }));
     });
+    pool
+        .command('prove')
+        .description('prove you control your pool account with your sign-in, and print the account and the time the pool stored, to send to the operator who asked for proof before acting on your request (GDPR Article 12(6)); for a closed account, run login instead')
+        .option(serverOption, serverHelp)
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await poolProve(deps, { server: text(options, 'server') }));
+    });
+    pool
+        .command('export')
+        .description('save a copy of what the pool holds about your account to a folder, as JSON, one file a page, and write nothing to the pool; with --raw also save your own raw transcripts that still stand (GDPR Articles 15 and 20)')
+        .requiredOption('--out <folder>', 'the folder to save the export in; its files are owner-only, and a rerun overwrites the same ones')
+        .option('--raw', 'also fetch each raw transcript you deposited that has not been erased, into <folder>/raw')
+        .option(serverOption, serverHelp)
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await poolExport(deps, { server: text(options, 'server'), out: text(options, 'out') ?? '', raw: flag(options, 'raw') }));
+    });
     pool
         .command('fetch')
         .description('fetch the signed bundle for one harness version, verify it against the key pinned at login, and keep it locally')
@@ -467,6 +594,53 @@ const buildProgram = (deps, observed) => {
         const options = command.optsWithGlobals();
         emit(deps, flag(options, 'json'), await poolFetch(deps, { server: text(options, 'server'), harness: text(options, 'harness'), harnessVersion: text(options, 'harnessVersion') ?? '' }));
     });
+    const club = program.command('club').description('private boards for people you invite (docs/pool.md, "Boards"): a club shows the nicknames of its members with weeks rowing, active days, sessions, and strokes this week, and never a session, project, prompt, or token; needs oars pool login');
+    club
+        .command('create')
+        .description('start a club and print its code once; you are its first member. Shows the consent text from the pool and asks you to type yes')
+        .argument('<name>', 'the name of the club (letters, digits, spaces, dots, underscores, and hyphens; 24 at most)')
+        .requiredOption('--nickname <name>', 'the name members of the club see for you (2 to 24 letters, digits, spaces, dots, underscores, or hyphens; no @ or link)')
+        .option(serverOption, serverHelp)
+        .action(async (name, _options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await clubCreate(deps, name, { server: text(options, 'server'), nickname: text(options, 'nickname') ?? '' }));
+    });
+    club
+        .command('join')
+        .description('join a club by its code, or the open board with the word open; shows the consent text from the pool for it and asks you to type yes')
+        .argument('<code>', 'the code of the club, or open')
+        .requiredOption('--nickname <name>', 'the name the board shows for you (2 to 24 letters, digits, spaces, dots, underscores, or hyphens; no @ or link)')
+        .option(serverOption, serverHelp)
+        .action(async (code, _options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await clubJoin(deps, code, { server: text(options, 'server'), nickname: text(options, 'nickname') ?? '' }));
+    });
+    club
+        .command('leave')
+        .description('leave a club: your row is gone from its board at once')
+        .argument('<club>', 'the id of the club, as oars club create or join printed it')
+        .option(serverOption, serverHelp)
+        .action(async (id, _options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await clubLeave(deps, id, { server: text(options, 'server') }));
+    });
+    club
+        .command('show')
+        .description('print the board of a club, in the order the pool gives: nickname, weeks rowing, active days, sessions, and strokes this week; members only')
+        .argument('<club>', 'the id of the club')
+        .option(serverOption, serverHelp)
+        .action(async (id, _options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await clubShow(deps, id, { server: text(options, 'server') }));
+    });
+    program
+        .command('board')
+        .description('print the open board: people who chose to join it and have 90 days of standing, ranked by weeks rowing, then active days; public, so it needs no sign-in')
+        .option(serverOption, serverHelp)
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await board(deps, { server: text(options, 'server') }));
+    });
     const telemetry = program.command('telemetry').description('what oars records about its own use, on this machine (docs/telemetry.md): status, on, off, show, and report');
     const telemetryJson = (command) => flag(command.optsWithGlobals(), 'json');
     telemetry
@@ -527,11 +701,23 @@ const execute = async (argv, deps, observed) => {
         return failure.exitCode;
     }
 };
+/** `sessions hook uninstall` is the first step of removing the store, so it must not start a sweep that would recreate what the person is about to delete. */
+const isHookUninstall = (observed) => observed.path.join(' ') === 'sessions hook uninstall';
+/** `sessions try` promises no network call and no read of the real store, and the sender does both. */
+const isSessionsTry = (observed) => observed.path.join(' ') === 'sessions try';
+/** The weekly card line (`sessions/card-line.ts`): stderr only, never an error, never a change to the exit code. */
+const weeklyLine = (argv, deps, observed) => deps.sessions === undefined
+    ? Promise.resolve('not_due')
+    : cardLine({ storeDir: deps.sessions.storeDir, telemetryDir: deps.telemetry?.dir, now: deps.now(), tty: deps.sessions.stderr?.isTTY === true, argv, path: observed.path, flags: observed.flags, stderr: deps.io.stderr });
 /** Runs one invocation (`argv` without the node and script entries) and returns the exit code. Telemetry records it afterward and cannot change it. */
 export const run = async (argv, deps) => {
     const observed = { path: [], flags: [] };
     const startedAt = deps.now();
     const exit = await execute(argv, deps, observed);
+    observed.cardLine = await weeklyLine(argv, deps, observed);
     finishTelemetry(deps, argv, observed, startedAt, exit);
+    // Never from a gate hook (it runs before every tool call) or from `hook uninstall`; it cannot change the exit code or what the command printed.
+    if (deps.catchUp !== undefined && !isHook(argv, observed) && !isHookUninstall(observed) && !isSessionsTry(observed))
+        await Promise.resolve().then(deps.catchUp).catch(() => undefined);
     return exit;
 };

package/dist/club.d.ts

@@ -0,0 +1,19 @@
+import type { Outcome, RunDeps } from './cli.js';
+interface Options {
+    server?: string | undefined;
+}
+/** `oars club create <name> --nickname <n>`: a new club with the caller as its first member. The code comes back once. */
+export declare const clubCreate: (deps: RunDeps, name: string, options: Options & {
+    nickname: string;
+}) => Promise<Outcome>;
+/** `oars club join <code> --nickname <n>`; the word `open` joins the open board under its own text. */
+export declare const clubJoin: (deps: RunDeps, code: string, options: Options & {
+    nickname: string;
+}) => Promise<Outcome>;
+/** `oars club leave <club>`: the row leaves every view at once. */
+export declare const clubLeave: (deps: RunDeps, club: string, options: Options) => Promise<Outcome>;
+/** `oars club show <club>`: the board, to its members only. */
+export declare const clubShow: (deps: RunDeps, club: string, options: Options) => Promise<Outcome>;
+/** `oars board`: the open board. It is public, so it needs no sign-in. */
+export declare const board: (deps: RunDeps, options: Options) => Promise<Outcome>;
+export {};

package/dist/club.js

@@ -0,0 +1,132 @@
+// `oars club` and `oars board` (t1091): the commands over the pool's board routes (docs/pool.md, "Boards"). A club shares counts with the people who hold its code; the open board is public. Joining is a person at a terminal who reads the pool's consent text and types yes, the way the covenant is accepted: a flag or a script on stdin is not that person.
+import { createHash } from 'node:crypto';
+import { CliError, exitCodeForProblem, ExitCode } from './errors.js';
+import { ask, isTerminal, lineFrom, poolServer, runtimeOf } from './sessions/pool-command.js';
+import { isObject, loadSignIns, numberIn, textIn } from './sessions/pool-replica.js';
+const CREATE = 'club-create';
+const JOIN = 'club-join';
+const LEAVE = 'club-leave';
+const SHOW = 'club-show';
+const BOARD = 'board';
+/** The word that names the open board where a club's code goes. */
+const OPEN_WORD = 'open';
+/** A plain span of time: seconds under two minutes, minutes under two hours, else hours. */
+const spanOf = (seconds) => {
+    if (seconds < 120)
+        return `${String(Math.max(1, Math.ceil(seconds)))} seconds`;
+    if (seconds < 7200)
+        return `${String(Math.ceil(seconds / 60))} minutes`;
+    return `${String(Math.ceil(seconds / 3600))} hours`;
+};
+const failure = (step, code, exit, message) => new CliError(`${code}: ${message}`, exit, step, { title: `${code}: ${message}`, code });
+/** The pool's named refusal with its code first (`club_full: ...`), and for a brake, when to try again. */
+const refused = (step, { status, body }) => {
+    // A token the pool no longer knows (revoked, or expired there) while the local sign-in still looks valid: the same cause as no sign-in at all.
+    if (status === 401)
+        return failure(step, 'not_signed_in', ExitCode.AUTH, 'the pool did not accept your sign-in. Run oars pool login first.');
+    const code = isObject(body) ? textIn(body, 'error') : undefined;
+    const said = (isObject(body) ? textIn(body, 'message') : undefined) ?? `The pool answered HTTP ${String(status)}.`;
+    const wait = isObject(body) ? numberIn(body, 'retry_after') : undefined;
+    const title = `${code === undefined ? '' : `${code}: `}${said}${code === 'rate_limited' && wait !== undefined ? ` Try again in ${spanOf(wait)}.` : ''}`;
+    const exit = status === 409 ? ExitCode.CONFLICT : status === 404 ? ExitCode.INVALID : exitCodeForProblem(status, code === undefined ? undefined : { code });
+    return new CliError(title, exit, step, { title, status, ...(code === undefined ? {} : { code }) });
+};
+/** The pool and the credential held for it, or `not_signed_in` before anything is shown or asked. */
+const credential = async (deps, step, options) => {
+    const server = poolServer(deps.env, step, options.server);
+    const found = (await loadSignIns(runtimeOf(deps).storeDir, step)).find((entry) => entry.server === server);
+    if (found === undefined || found.expiresAt <= deps.now())
+        throw failure(step, 'not_signed_in', ExitCode.AUTH, `you are not signed in to ${server}. Run oars pool login first.`);
+    return { server, token: found.token };
+};
+/** The text a person is shown before joining, read from the pool, and the hash of exactly those bytes. */
+const textOf = async (deps, server, which, step) => {
+    const reply = await ask(deps, step, server, '/v1/clubs/consent', {});
+    const entry = isObject(reply.body) ? Reflect.get(reply.body, which) : undefined;
+    const text = isObject(entry) ? textIn(entry, 'text') : undefined;
+    if (reply.status !== 200 || text === undefined)
+        throw reply.status === 200 ? new CliError('The pool did not state the consent text for this board.', ExitCode.UNEXPECTED, step) : refused(step, reply);
+    return { text, sha256: createHash('sha256').update(text).digest('hex') };
+};
+/** Shows the consent text and reads yes from a person at a terminal. Nothing is sent without it. */
+const agreed = async (deps, step, text) => {
+    if (!isTerminal(deps))
+        throw failure(step, 'consent_not_given', ExitCode.AUTH, 'agreeing takes a person at a terminal who reads the text and types yes: run this command from one. Nothing was sent.');
+    deps.io.stderr(`\n${text}\n\nType yes to agree, anything else to stop.\n> `);
+    const typed = await lineFrom(runtimeOf(deps).stdin);
+    if (typed?.trim().toLowerCase() !== 'yes')
+        throw failure(step, 'consent_not_given', ExitCode.AUTH, `${typed === undefined ? 'No answer was typed' : 'That was not yes'}. Nothing was sent.`);
+};
+const stringIn = (body, key) => (isObject(body) ? (textIn(body, key) ?? '') : '');
+/** `oars club create <name> --nickname <n>`: a new club with the caller as its first member. The code comes back once. */
+export const clubCreate = async (deps, name, options) => {
+    const { server, token } = await credential(deps, CREATE, options);
+    const consent = await textOf(deps, server, 'club', CREATE);
+    await agreed(deps, CREATE, consent.text);
+    const reply = await ask(deps, CREATE, server, '/v1/clubs', { token, body: { name, nickname: options.nickname, consent: consent.sha256 } });
+    if (reply.status !== 201)
+        throw refused(CREATE, reply);
+    const [id, code] = [stringIn(reply.body, 'id'), stringIn(reply.body, 'code')];
+    return {
+        document: { ok: true, id, name, nickname: options.nickname, code },
+        text: [`Club "${name}" created. You are ${options.nickname}.`, `Code: ${code}`, 'This is the only time the code is shown. Share it only with the people you want in the club: anyone who holds it can join.', `See the board with: oars club show ${id}`].join('\n'),
+    };
+};
+/** `oars club join <code> --nickname <n>`; the word `open` joins the open board under its own text. */
+export const clubJoin = async (deps, code, options) => {
+    const { server, token } = await credential(deps, JOIN, options);
+    const open = code.trim().toLowerCase() === OPEN_WORD;
+    const consent = await textOf(deps, server, open ? 'open' : 'club', JOIN);
+    await agreed(deps, JOIN, consent.text);
+    const reply = await ask(deps, JOIN, server, '/v1/clubs/join', { token, body: { code, nickname: options.nickname, consent: consent.sha256 } });
+    if (reply.status !== 200)
+        throw refused(JOIN, reply);
+    const [id, name] = [stringIn(reply.body, 'id'), stringIn(reply.body, 'name')];
+    return {
+        document: { ok: true, id, name, nickname: options.nickname },
+        text: [`Joined "${name}" as ${options.nickname}.`, ...(open ? ['Your row shows on the open board once your account has 90 days of standing.'] : []), `Leave any time with: oars club leave ${id}`].join('\n'),
+    };
+};
+/** `oars club leave <club>`: the row leaves every view at once. */
+export const clubLeave = async (deps, club, options) => {
+    const { server, token } = await credential(deps, LEAVE, options);
+    const reply = await ask(deps, LEAVE, server, `/v1/clubs/${encodeURIComponent(club)}/me`, { token, method: 'DELETE' });
+    if (reply.status !== 204)
+        throw refused(LEAVE, reply);
+    return { document: { ok: true, id: club, left: true }, text: 'You left the club. Your row is gone from its board.' };
+};
+const rowsOf = (body) => {
+    const members = isObject(body) ? Reflect.get(body, 'members') : undefined;
+    const rows = [];
+    for (const member of Array.isArray(members) ? members : []) {
+        if (!isObject(member))
+            continue;
+        rows.push({ place: numberIn(member, 'place') ?? rows.length + 1, nickname: textIn(member, 'nickname') ?? '', ashore: Reflect.get(member, 'ashore') === true, weeksRowing: numberIn(member, 'weeksRowing') ?? 0, activeDays: numberIn(member, 'activeDays') ?? 0, sessions: numberIn(member, 'sessions') ?? 0, strokesThisWeek: numberIn(member, 'strokesThisWeek') ?? 0 });
+    }
+    return rows;
+};
+/** The board as lines, in the pool's order: a member with no counting week is "ashore" and has no numbers. */
+const tableOf = (rows) => {
+    const head = ['#', 'nickname', 'weeks rowing', 'active days', 'sessions', 'strokes this week'];
+    const body = rows.map((row) => [String(row.place), row.nickname, ...(row.ashore ? ['ashore', '', '', ''] : [String(row.weeksRowing), String(row.activeDays), String(row.sessions), String(row.strokesThisWeek)])]);
+    const widths = head.map((title, at) => Math.max(title.length, ...body.map((line) => (line[at] ?? '').length)));
+    return [head, ...body].map((line) => line.map((cell, at) => cell.padEnd(widths[at] ?? 0)).join('  ').trimEnd()).join('\n');
+};
+/** `oars club show <club>`: the board, to its members only. */
+export const clubShow = async (deps, club, options) => {
+    const { server, token } = await credential(deps, SHOW, options);
+    const reply = await ask(deps, SHOW, server, `/v1/clubs/${encodeURIComponent(club)}`, { token });
+    if (reply.status !== 200 || !isObject(reply.body))
+        throw refused(SHOW, reply);
+    const rows = rowsOf(reply.body);
+    return { document: { ok: true, ...reply.body }, text: `${stringIn(reply.body, 'name')}\n${tableOf(rows)}` };
+};
+/** `oars board`: the open board. It is public, so it needs no sign-in. */
+export const board = async (deps, options) => {
+    const server = poolServer(deps.env, BOARD, options.server);
+    const reply = await ask(deps, BOARD, server, '/v1/board', {});
+    if (reply.status !== 200 || !isObject(reply.body))
+        throw refused(BOARD, reply);
+    const rows = rowsOf(reply.body);
+    return { document: { ok: true, ...reply.body }, text: rows.length === 0 ? 'No one is on the open board yet.' : `Open board\n${tableOf(rows)}` };
+};

package/dist/gate/hook-fill-main.js

@@ -1,4 +1,4 @@
-// The entry the hook starts, detached, after a cut ask: `node hook-fill-main.js <storeDir> <class> <name> <cwd>`. It prints nothing, answers nothing, and exits 0 whatever
+// The entry the hook starts, detached, at the hand-off mark or after an ask with no time to start: `node hook-fill-main.js <storeDir> <class> <name> <cwd>`. It prints nothing, answers nothing, and exits 0 whatever
 // happens; nobody waits on it.
 import { CROSSING_CLASSES } from './checks.js';
 import { FILL_TIMEOUT_MS, runFill } from './hook-fill.js';

package/dist/gate/hook-fill.d.ts

@@ -27,7 +27,7 @@ export type HelperSpawn = (command: string, args: string[], options: {
 /** The helper outlives the hook: detached, no stdio, never waited on, so the harness's call does not wait for it either. One that cannot start never releases its lock, so the lock goes on its `error`. */
 export declare const startHelper: (spawn: HelperSpawn, storeDir: string, ask: FillAsk) => void;
 /**
- * Called by the hook after a cut ask: takes the lock and starts the helper. Nothing here throws into the hook: a store that cannot be written, or a helper that cannot
+ * Called by the hook at the hand-off mark, or after an ask with no time to start: takes the lock and starts the helper. Nothing here throws into the hook: a store that cannot be written, or a helper that cannot
  * start, is an answer that does not come. The lock goes when the start throws, so the next sight asks about the name again.
  */
 export declare const startFill: (storeDir: string, ask: FillAsk, now: number, start: (storeDir: string, ask: FillAsk) => void) => Promise<void>;

package/dist/gate/hook-fill.js

@@ -61,7 +61,7 @@ export const startHelper = (spawn, storeDir, ask) => {
     child.unref();
 };
 /**
- * Called by the hook after a cut ask: takes the lock and starts the helper. Nothing here throws into the hook: a store that cannot be written, or a helper that cannot
+ * Called by the hook at the hand-off mark, or after an ask with no time to start: takes the lock and starts the helper. Nothing here throws into the hook: a store that cannot be written, or a helper that cannot
  * start, is an answer that does not come. The lock goes when the start throws, so the next sight asks about the name again.
  */
 export const startFill = async (storeDir, ask, now, start) => {

package/dist/gate/hook-main.js

@@ -5,14 +5,15 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { defaultConfigDir } from '../credentials.js';
-import { DEADLINE_MS } from './hook.js';
+import { deadlineOf, handOffMarkOf } from './hook.js';
 import { isLocked, startFill, startHelper } from './hook-fill.js';
 import { fireRecorder } from './hook-record.js';
 import { runHookProcess } from './hook-process.js';
 import { managerReader } from './registry.js';
 import { hookEmitter } from '../telemetry/hook-emit.js';
-/** The process itself ends this long after `DEADLINE_MS`. */
+/** The process itself ends this long after the deadline. */
 const GRACE_MS = 100;
+const deadlineMs = deadlineOf(process.env);
 const readStdin = async () => {
     process.stdin.setEncoding('utf8');
     let text = '';
@@ -27,8 +28,9 @@ const depsFor = (stage) => {
         now: Date.now,
         // `performance.now()` counts from the start of the process, so node's own start is inside the budget.
         clock: () => performance.now(),
-        deadlineMs: DEADLINE_MS,
-        registry: managerReader(undefined, DEADLINE_MS),
+        deadlineMs,
+        handOffMarkMs: handOffMarkOf(process.env, deadlineMs),
+        registry: managerReader(undefined, deadlineMs),
         fill: (ask) => startFill(storeDir, ask, Date.now(), (dir, one) => { startHelper(spawn, dir, one); }),
         locked: (ask) => isLocked(storeDir, ask, Date.now()),
         stage,
@@ -41,7 +43,7 @@ await runHookProcess({
     deps: depsFor,
     exit: (code) => process.exit(code),
     write: (text) => new Promise((done) => process.stdout.write(text, () => { done(); })),
-    deadlineMs: DEADLINE_MS + GRACE_MS - performance.now(),
+    deadlineMs: deadlineMs + GRACE_MS - performance.now(),
     clock: () => performance.now(),
     record: fireRecorder(emit),
 });