@manyoars/oars 0.4.0 → 0.5.1

package/dist/sessions/machine-child.js

@@ -0,0 +1,120 @@
+// What the detached child of a machine Stop does (`hook-bin.js machine-child <input>`, started by `machine-stop.ts`): capture the session's transcript, build its batch into the outbox, then hold the batch on the session's own branch. One child at a time per outbox, on the send
+// lock: a Stop that finds the lock held writes the dirty mark (`send.dirty`, one input per line) and leaves, and the holder takes the mark and runs those sessions too before it lets go, so the last Stop of a burst is
+// always built from the transcript as it ended. Before each extraction the child waits for the transcript to stop growing, because Stop can fire while the harness is still writing the last lines.
+import { rename, readFile, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { appendOwnerOnly, mkdirOwnerOnly } from './owner-only.js';
+import { SendLockBusy, withSendLock } from './pool-send-lock.js';
+export const SETTLE = { quietMs: 2000, maxMs: 15_000, pollMs: 250 };
+const DIRTY = 'send.dirty';
+/** The input a Stop forwarded, or `undefined` when it names no session or transcript. */
+export const parseChildInput = (text) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const session = Reflect.get(parsed, 'session_id');
+    const transcript = Reflect.get(parsed, 'transcript_path');
+    const cwd = Reflect.get(parsed, 'cwd');
+    if (typeof session !== 'string' || session === '' || typeof transcript !== 'string' || transcript === '')
+        return undefined;
+    return { session, transcript, cwd: typeof cwd === 'string' && cwd !== '' ? cwd : undefined };
+};
+/** Waits until the transcript has been the same size for `quietMs`, at most `maxMs` in all. */
+export const settle = async (path, deps, times = SETTLE) => {
+    const start = deps.now();
+    let last = await deps.size(path);
+    let changed = start;
+    for (;;) {
+        const at = deps.now();
+        if (at - changed >= times.quietMs)
+            return 'quiet';
+        if (at - start >= times.maxMs)
+            return 'timeout';
+        await deps.sleep(times.pollMs);
+        const size = await deps.size(path);
+        if (size !== last) {
+            last = size;
+            changed = deps.now();
+        }
+    }
+};
+/** The session's own latest input wins, in the order the sessions were first named. */
+const byLatest = (inputs) => [...new Map(inputs.map((input) => [input.session, input])).values()];
+/** One line in the wire shape a Stop forwards, so the holder reads a mark with the one parser. */
+const markDirty = async (outbox, input) => {
+    // The mark holds a transcript path and a folder, so it is owner-only like the rest of the outbox.
+    await mkdirOwnerOnly(outbox);
+    await appendOwnerOnly(join(outbox, DIRTY), `${JSON.stringify({ session_id: input.session, transcript_path: input.transcript, cwd: input.cwd })}\n`);
+};
+const hasDirty = (outbox) => stat(join(outbox, DIRTY)).then(() => true, () => false);
+/** Claims the mark by renaming it, so two takers never read one mark and a Stop writing after the claim starts a mark of its own. */
+const takeDirty = async (outbox) => {
+    const claimed = join(outbox, `${DIRTY}.${String(process.pid)}`);
+    try {
+        await rename(join(outbox, DIRTY), claimed);
+    }
+    catch {
+        return [];
+    }
+    const lines = (await readFile(claimed, 'utf8').catch(() => '')).split('\n');
+    await rm(claimed, { force: true });
+    return lines.flatMap((line) => {
+        const input = line === '' ? undefined : parseChildInput(line);
+        return input === undefined ? [] : [input];
+    });
+};
+/** One session: check its repository against the allow list, wait for the transcript to settle, capture it, build its batch, and hold the batch. A session off the list is not captured, so its transcript is never copied into the store; nothing is withdrawn either. */
+const extract = async (deps, input) => {
+    if (!(await deps.allowed(input)))
+        return;
+    await settle(input.transcript, deps, deps.settle);
+    await deps.capture(input);
+    await deps.build(input);
+    await deps.hold(input);
+    await deps.send?.();
+};
+/** Takes the lock without waiting and runs `work`, then every session marked dirty meanwhile; `false` when another child holds it. The first failure is rethrown once every session has had its turn. */
+const locked = async (deps, work) => {
+    try {
+        await withSendLock(deps.outbox, async () => {
+            let failure;
+            for (let pending = byLatest([...work, ...(await takeDirty(deps.outbox))]); pending.length > 0; pending = byLatest(await takeDirty(deps.outbox))) {
+                for (const input of pending) {
+                    try {
+                        await extract(deps, input);
+                    }
+                    catch (error) {
+                        failure ??= error instanceof Error ? error : new Error(String(error));
+                    }
+                }
+            }
+            if (failure !== undefined)
+                throw failure;
+        }, { ...deps.lock, waitMs: 0 });
+        return true;
+    }
+    catch (error) {
+        if (error instanceof SendLockBusy)
+            return false;
+        throw error;
+    }
+};
+/**
+ * `built` when this child ran the session (and anything marked while it did), `marked` when another child held the lock and the mark is left for it. Two windows are closed on purpose: a Stop that marks just after the holder's last look
+ * finds the lock free on its second try, and a holder that lets go while a mark is being written looks once more after it has released.
+ */
+export const machineChild = async (deps, input) => {
+    if (await locked(deps, [input])) {
+        if (await hasDirty(deps.outbox))
+            await locked(deps, []);
+        return 'built';
+    }
+    await markDirty(deps.outbox, input);
+    return (await locked(deps, [])) ? 'built' : 'marked';
+};

package/dist/sessions/machine-credential.d.ts

@@ -0,0 +1,10 @@
+import type { MachineClass } from './machine.js';
+export interface MachineCredential {
+    source: 'proxy' | 'key' | 'token';
+    /** Absent for the proxy: the request carries no Authorization header. */
+    token?: string;
+}
+export declare const keyFile: (storeDir: string) => string;
+export declare const tokenFile: (env: NodeJS.ProcessEnv, storeDir: string) => string;
+/** The credential this machine presents, or `undefined` when it holds none (a hold-only machine, or one whose enrollment token was never put on it). */
+export declare const credentialOf: (hostClass: MachineClass, env: NodeJS.ProcessEnv, storeDir: string) => Promise<MachineCredential | undefined>;

package/dist/sessions/machine-credential.js

@@ -0,0 +1,20 @@
+// The machine child's pool credential, in one place. A cloud machine's secret is held by the runtime's proxy (a network secret on the pool's host, added outside the VM, so the VM never sees it), so the child sends no Authorization header. Any other class holds
+// its own: the key an earlier run rotated to (`machine-key`, owner-only in the store), else the enrollment's token (`machine-token` in the store, or the file `OARS_MACHINE_TOKEN_FILE` names). The value is read when asked and never kept, logged, or put in a notice.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const keyFile = (storeDir) => join(storeDir, 'machine-key');
+export const tokenFile = (env, storeDir) => {
+    const named = env.OARS_MACHINE_TOKEN_FILE?.trim();
+    return named === undefined || named === '' ? join(storeDir, 'machine-token') : named;
+};
+const valueOf = (file) => readFile(file, 'utf8').then((text) => (text.trim() === '' ? undefined : text.trim()), () => undefined);
+/** The credential this machine presents, or `undefined` when it holds none (a hold-only machine, or one whose enrollment token was never put on it). */
+export const credentialOf = async (hostClass, env, storeDir) => {
+    if (hostClass === 'cloud')
+        return { source: 'proxy' };
+    const key = await valueOf(keyFile(storeDir));
+    if (key !== undefined)
+        return { source: 'key', token: key };
+    const token = await valueOf(tokenFile(env, storeDir));
+    return token === undefined ? undefined : { source: 'token', token };
+};

package/dist/sessions/machine-enroll.d.ts

@@ -0,0 +1,47 @@
+import type { Outcome, RunDeps } from '../cli.js';
+/** How a session starts on the machine; the pool records it with the machine (cloud self-deposit, enrollment). */
+export declare const LAUNCHERS: readonly ["interactive", "orchestrated", "scheduled"];
+/** What a repository's record says about it. `unknown` is any answer that does not say, and is refused like `public`. */
+export type Visibility = (repo: string) => Promise<'private' | 'public' | 'unknown'>;
+export interface EnrollOptions {
+    holdOnly: boolean;
+    hostClass: string | undefined;
+    launcher: string | undefined;
+    /** `owner/name` entries, each possibly several joined by commas or spaces. */
+    allowRepos: readonly string[];
+    /** The full enrollment's label for the machine, as the pool lists it. */
+    name?: string | undefined;
+    /** `--days` as typed: how long the key lives from its activation. */
+    days?: string | undefined;
+    server?: string | undefined;
+}
+/** The check against GitHub's own repository record, `private` true or false. A repository the token cannot see answers 404, which says nothing, so it is `unknown`, as is every error and every record with no flag. */
+export declare const githubVisibility: (get: typeof fetch, token: string | undefined) => Visibility;
+/** The trusted machine's record of the machines it enrolled, one JSON line each. `oars pool hold pull` reads it (`readMachines`) to refuse a branch naming a machine it does not hold, and to write that machine's `claimed` into the batch it admits. */
+export declare const machinesFile: (storeDir: string) => string;
+/** What an enrollment records about its machine. */
+export interface MachineRecord {
+    machine: string;
+    hostClass: string;
+    launcher: string;
+    allowRepos: readonly string[];
+}
+/**
+ * The machines this one enrolled, in the order it enrolled them. A line that is not a record (not JSON, a missing field, a repository that is not owner/name) is left out, so its machine reads as unknown and its branches are refused
+ * rather than admitted on a claim nobody can read. A file that exists and cannot be read throws, as `recordMachine` does.
+ */
+export declare const readMachines: (storeDir: string) => Promise<MachineRecord[]>;
+/**
+ * Prints the env block for a machine that holds its deposit in its own private repository. Without `--hold-only` it also asks the pool for a one-time enrollment token after every check has passed, and records the
+ * machine only after the pool has answered. Everything it refuses, it refuses before it asks GitHub anything: the flags, then the term list (a block with no terms
+ * would exclude every session, so nothing would be held). A repository that is public, or whose record cannot be read, refuses the whole block, and the message names each such repository.
+ */
+export declare const poolEnroll: (deps: RunDeps, options: EnrollOptions, visibility: Visibility) => Promise<Outcome>;
+/** `oars pool machines`: the account's machines, one line each, with the id `machines revoke` takes. */
+export declare const poolMachines: (deps: RunDeps, options: {
+    server?: string | undefined;
+}) => Promise<Outcome>;
+/** `oars pool machines revoke <id>`: effective on the machine's next request. The pool answers 404 for an id that is not this account's and for one already revoked. */
+export declare const poolMachineRevoke: (deps: RunDeps, id: string, options: {
+    server?: string | undefined;
+}) => Promise<Outcome>;

package/dist/sessions/machine-enroll.js

@@ -0,0 +1,230 @@
+// `oars pool enroll`: the whole configuration a cloud VM needs to hold its deposit in its own private repository, printed as one env block. With `--hold-only` it uses no pool credential (the pool may not exist yet); without it,
+// the pool is also asked for a one-time enrollment token after every check below, and the machine is recorded only after the pool answers.
+// The trusted machine mints the machine id, derives the two salts from its own (so a local capture and a VM's key one repository the same way), reads its term file, and refuses any repository that is not
+// private: a hold branch is exactly as readable as the repository it sits in.
+import { randomBytes } from 'node:crypto';
+import { readFile, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CliError, ExitCode } from '../errors.js';
+import { exclusionPaths, loadTerms } from './exclusion.js';
+import { derivedSalt } from './machine-ids.js';
+import { HOST_CLASSES } from './machine.js';
+import { isMissing, mkdirOwnerOnly, writeOwnerOnly } from './owner-only.js';
+import { ask, poolServer, refusal, runtimeOf, signedIn } from './pool-command.js';
+import { isObject, numberIn, textIn } from './pool-replica.js';
+import { localSalt } from './store.js';
+const STEP = 'pool-enroll';
+/** How a session starts on the machine; the pool records it with the machine (cloud self-deposit, enrollment). */
+export const LAUNCHERS = ['interactive', 'orchestrated', 'scheduled'];
+const usage = (message) => new CliError(message, ExitCode.USAGE, STEP);
+const REPO_NAME = /^[\w.-]+\/[\w.-]+$/u;
+/** The check against GitHub's own repository record, `private` true or false. A repository the token cannot see answers 404, which says nothing, so it is `unknown`, as is every error and every record with no flag. */
+export const githubVisibility = (get, token) => async (repo) => {
+    try {
+        const headers = { accept: 'application/vnd.github+json', 'user-agent': 'oars' };
+        if (token !== undefined && token !== '')
+            headers.authorization = `Bearer ${token}`;
+        const reply = await get(`https://api.github.com/repos/${repo}`, { headers, redirect: 'error', signal: AbortSignal.timeout(15_000) });
+        if (!reply.ok)
+            return 'unknown';
+        const record = await reply.json();
+        const flag = typeof record === 'object' && record !== null ? Reflect.get(record, 'private') : undefined;
+        if (flag === true)
+            return 'private';
+        return flag === false ? 'public' : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+};
+/** The trusted machine's record of the machines it enrolled, one JSON line each. `oars pool hold pull` reads it (`readMachines`) to refuse a branch naming a machine it does not hold, and to write that machine's `claimed` into the batch it admits. */
+export const machinesFile = (storeDir) => join(storeDir, 'machines.jsonl');
+/** The file's text; a store that has enrolled no machine has none yet, and any other read error is the caller's. */
+const machinesText = (storeDir) => readFile(machinesFile(storeDir), 'utf8').catch((error) => {
+    if (isMissing(error))
+        return '';
+    throw error;
+});
+/** Appends `record` as one line. The new file is staged beside the old one, owner-only, and renamed onto its name, so a reader sees the old list or the new one, and a crash leaves the old one. */
+const recordMachine = async (storeDir, record) => {
+    const file = machinesFile(storeDir);
+    const staged = `${file}.${String(process.pid)}`;
+    await writeOwnerOnly(staged, `${await machinesText(storeDir)}${JSON.stringify(record)}\n`);
+    await rename(staged, file);
+};
+const recordOf = (line) => {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const machine = Reflect.get(value, 'machine');
+    const hostClass = Reflect.get(value, 'hostClass');
+    const launcher = Reflect.get(value, 'launcher');
+    const allowRepos = Reflect.get(value, 'allowRepos');
+    if (typeof machine !== 'string' || typeof hostClass !== 'string' || typeof launcher !== 'string' || !Array.isArray(allowRepos))
+        return undefined;
+    const repos = allowRepos;
+    return repos.every((repo) => typeof repo === 'string' && REPO_NAME.test(repo)) ? { machine, hostClass, launcher, allowRepos: repos } : undefined;
+};
+/**
+ * The machines this one enrolled, in the order it enrolled them. A line that is not a record (not JSON, a missing field, a repository that is not owner/name) is left out, so its machine reads as unknown and its branches are refused
+ * rather than admitted on a claim nobody can read. A file that exists and cannot be read throws, as `recordMachine` does.
+ */
+export const readMachines = async (storeDir) => (await machinesText(storeDir)).split('\n').flatMap((line) => recordOf(line) ?? []);
+const quoted = (value) => `"${value.replace(/[\\"]/gu, '\\$&')}"`;
+const classOf = (given) => {
+    const found = HOST_CLASSES.find((name) => name === given && name !== 'local');
+    if (found === undefined)
+        throw usage(`--host-class takes one of ${HOST_CLASSES.filter((name) => name !== 'local').join(', ')}; got ${given ?? 'nothing'}. Nothing was checked.`);
+    return found;
+};
+const launcherOf = (given) => {
+    const found = LAUNCHERS.find((name) => name === given);
+    if (found === undefined)
+        throw usage(`--launcher takes one of ${LAUNCHERS.join(', ')}; got ${given ?? 'nothing'}. Nothing was checked.`);
+    return found;
+};
+const reposOf = (given) => {
+    const repos = [...new Set(given.flatMap((entry) => entry.split(/[\s,]+/u)).filter((entry) => entry !== '').map((entry) => entry.toLowerCase()))];
+    if (repos.length === 0)
+        throw usage('--allow-repos takes the repositories this machine may hold, as owner/name. Nothing was checked.');
+    const bad = repos.find((repo) => !REPO_NAME.test(repo) || repo.split('/').some((part) => /^\.+$/u.test(part)));
+    if (bad !== undefined)
+        throw usage(`--allow-repos takes owner/name; got ${bad}. Nothing was checked.`);
+    return repos;
+};
+/** `--days` as the pool takes it, or left out for the pool's default. The wording is the pool's own. */
+const daysOf = (given) => {
+    if (given === undefined)
+        return undefined;
+    const days = /^\d+$/u.test(given) ? Number(given) : Number.NaN;
+    if (!Number.isSafeInteger(days) || days < 1 || days > 365)
+        throw usage('--days is a whole number of days from 1 to 365. Nothing was checked.');
+    return days;
+};
+const enrolledOf = (body) => {
+    const machine = isObject(body) ? Reflect.get(body, 'machine') : undefined;
+    const token = isObject(body) ? textIn(body, 'token') : undefined;
+    const poolId = isObject(machine) ? textIn(machine, 'id') : undefined;
+    const tokenExpiresAt = isObject(machine) ? numberIn(machine, 'expiresAt') : undefined;
+    if (token === undefined || poolId === undefined || tokenExpiresAt === undefined)
+        throw new CliError('The pool did not answer the enrollment with a token and a machine.', ExitCode.UNEXPECTED, STEP);
+    return { token, tokenExpiresAt, poolId };
+};
+/**
+ * Prints the env block for a machine that holds its deposit in its own private repository. Without `--hold-only` it also asks the pool for a one-time enrollment token after every check has passed, and records the
+ * machine only after the pool has answered. Everything it refuses, it refuses before it asks GitHub anything: the flags, then the term list (a block with no terms
+ * would exclude every session, so nothing would be held). A repository that is public, or whose record cannot be read, refuses the whole block, and the message names each such repository.
+ */
+export const poolEnroll = async (deps, options, visibility) => {
+    const hostClass = classOf(options.hostClass);
+    if (!options.holdOnly && hostClass === 'hosted')
+        throw usage('The pool enrolls a vps, cloud, or ci machine; a hosted run uses a per-run token, so it does not enroll. Nothing was checked.');
+    const launcher = launcherOf(options.launcher);
+    const repos = reposOf(options.allowRepos);
+    if (options.holdOnly && (options.days !== undefined || options.name !== undefined || options.server !== undefined))
+        throw usage('--name, --days, and --server belong to the enrollment that asks the pool for a token; --hold-only sends nothing to the pool. Nothing was checked.');
+    const days = options.holdOnly ? undefined : daysOf(options.days);
+    if (!options.holdOnly && (options.name === undefined || options.name === ''))
+        throw usage('--name takes the label the pool lists this machine by. Nothing was checked.');
+    const runtime = runtimeOf(deps);
+    const termsFile = exclusionPaths(runtime.projectsRoot, deps.env).terms;
+    const terms = [...new Set(await loadTerms(termsFile))];
+    if (terms.length === 0)
+        throw usage(`No exclusion terms in ${termsFile}: a block without them would exclude every session, and nothing would be held. Nothing was checked.`);
+    // The sign-in is read from this machine's store (no network), so a signed-out run is refused before GitHub is asked about any repository. The pool itself is asked only after every repository is confirmed private, and the machine is recorded only after the pool has answered: a refusal at either leaves nothing behind.
+    const server = options.holdOnly ? '' : poolServer(deps.env, STEP, options.server);
+    const credential = options.holdOnly ? undefined : await signedIn(deps, runtime.storeDir, server, STEP);
+    const refused = [];
+    for (const repo of repos) {
+        const seen = await visibility(repo);
+        if (seen === 'public')
+            refused.push(`  ${repo} is public: a hold branch there is readable by anyone.`);
+        else if (seen === 'unknown')
+            refused.push(`  ${repo}: could not confirm it is private (the check needs a GH_TOKEN or GITHUB_TOKEN that can read it, and the repository's current name).`);
+    }
+    if (refused.length > 0)
+        throw usage(`Refusing to enroll: every repository must be private.\n${refused.join('\n')}`);
+    await mkdirOwnerOnly(runtime.storeDir);
+    const localKey = (await (runtime.accountSalt ?? localSalt)(runtime.storeDir)).salt;
+    const env = {
+        OARS_HOST_CLASS: hostClass,
+        OARS_LAUNCHER: launcher,
+        OARS_MACHINE: randomBytes(8).toString('hex'),
+        OARS_ALLOW_REPOS: repos.join(','),
+        OARS_REPO_SALT: derivedSalt(localKey, 'repoKey/1'),
+        OARS_SESSION_SALT: derivedSalt(localKey, 'sessionId/1'),
+        OARS_EXCLUSION_TERMS_INLINE: terms.join('\n'),
+        // A hold-only machine has no pool key; the marker keeps its child from reporting an unknown credential.
+        ...(options.holdOnly ? { OARS_HOLD_ONLY: '1' } : {}),
+    };
+    const enrolled = credential === undefined
+        ? undefined
+        : await askToEnroll(deps, server, credential.token, { label: options.name ?? '', hostClass, launcher, allowRepos: repos, ...(days === undefined ? {} : { days }) });
+    // Recorded after every check has passed (and the pool has answered, in a full enrollment) and before the block is printed: a block the operator can copy always names a machine the trusted side knows.
+    await recordMachine(runtime.storeDir, { machine: env.OARS_MACHINE, hostClass, launcher, allowRepos: repos });
+    const lines = Object.entries(env).map(([name, value]) => `${name}=${name === 'OARS_EXCLUSION_TERMS_INLINE' ? quoted(value) : value}`);
+    const count = `${String(repos.length)} private ${repos.length === 1 ? 'repository' : 'repositories'}`;
+    const block = ['', ...lines, '', 'A change to your term list needs this run again and the new block set in every environment.'];
+    if (enrolled === undefined) {
+        const text = [`Hold-only enrollment for ${count}. No pool credential was used or needed.`, 'Set these variables in the cloud environment. The block holds two salts and your exclusion terms, so treat it as a secret:', ...block].join('\n');
+        return { document: { ok: true, holdOnly: true, hostClass, launcher, machine: env.OARS_MACHINE, allowRepos: repos, env }, text };
+    }
+    const text = [
+        `Enrolled ${options.name ?? ''} with the pool for ${count}.`,
+        `One-time enrollment token (shown once; it must be activated within 24 hours, by ${new Date(enrolled.tokenExpiresAt).toISOString()}, or it is useless):`,
+        `  ${enrolled.token}`,
+        `Hold it where the runtime keeps secrets: a network secret on the cloud environment (Bearer, host ${new URL(server).host}), or an owner-only file on a server. Never in a repository.`,
+        'Set these variables in the cloud environment. The block holds two salts and your exclusion terms, so treat it as a secret:',
+        ...block,
+    ].join('\n');
+    return { document: { ok: true, holdOnly: false, hostClass, launcher, machine: env.OARS_MACHINE, poolMachine: enrolled.poolId, token: enrolled.token, tokenExpiresAt: enrolled.tokenExpiresAt, allowRepos: repos, env }, text };
+};
+/** `POST /v1/machines/enroll` with the account's credential. Any answer but the 201 is the pool's own refusal, and nothing is recorded. */
+const askToEnroll = async (deps, server, token, declared) => {
+    const reply = await ask(deps, STEP, server, '/v1/machines/enroll', { token, body: declared });
+    if (reply.status !== 201)
+        throw refusal(STEP, reply);
+    return enrolledOf(reply.body);
+};
+const MACHINES = 'pool-machines';
+const listedOf = (row) => {
+    const [id, label, hostClass, launcher, state] = ['id', 'label', 'hostClass', 'launcher', 'state'].map((name) => (isObject(row) ? textIn(row, name) : undefined));
+    const expiresAt = isObject(row) ? numberIn(row, 'expiresAt') : undefined;
+    if (id === undefined || label === undefined || hostClass === undefined || launcher === undefined || state === undefined || expiresAt === undefined) {
+        throw new CliError('The pool listed a machine this client cannot read.', ExitCode.UNEXPECTED, MACHINES);
+    }
+    return { id, label, hostClass, launcher, state, lastDepositDay: isObject(row) ? (textIn(row, 'lastDepositDay') ?? null) : null, expiresAt };
+};
+/** `oars pool machines`: the account's machines, one line each, with the id `machines revoke` takes. */
+export const poolMachines = async (deps, options) => {
+    const { storeDir } = runtimeOf(deps);
+    const server = poolServer(deps.env, MACHINES, options.server);
+    const { token } = await signedIn(deps, storeDir, server, MACHINES);
+    const reply = await ask(deps, MACHINES, server, '/v1/machines', { token });
+    const rows = isObject(reply.body) ? Reflect.get(reply.body, 'machines') : undefined;
+    if (reply.status === 200 && !Array.isArray(rows))
+        throw new CliError('The pool did not answer with a list of machines.', ExitCode.UNEXPECTED, MACHINES);
+    if (reply.status !== 200 || !Array.isArray(rows))
+        throw refusal(MACHINES, reply);
+    const machines = rows.map(listedOf);
+    const lines = machines.map((one) => `${one.label}  ${one.id}  ${one.hostClass}  ${one.launcher}  ${one.state}  last deposit ${one.lastDepositDay ?? 'never'}  expires ${new Date(one.expiresAt).toISOString().slice(0, 10)}`);
+    return { document: { ok: true, server, machines }, text: machines.length === 0 ? `No machines are enrolled with ${server}. oars pool enroll adds one.` : lines.join('\n') };
+};
+/** `oars pool machines revoke <id>`: effective on the machine's next request. The pool answers 404 for an id that is not this account's and for one already revoked. */
+export const poolMachineRevoke = async (deps, id, options) => {
+    const { storeDir } = runtimeOf(deps);
+    const server = poolServer(deps.env, MACHINES, options.server);
+    const { token } = await signedIn(deps, storeDir, server, MACHINES);
+    const reply = await ask(deps, MACHINES, server, `/v1/machines/${encodeURIComponent(id)}`, { method: 'DELETE', token });
+    if (reply.status === 404)
+        throw new CliError(`No machine ${id} to revoke: it is not one of this account's machines, or it is already revoked. oars pool machines lists them.`, ExitCode.USAGE, MACHINES);
+    if (reply.status !== 204)
+        throw refusal(MACHINES, reply);
+    return { document: { ok: true, server, revoked: id }, text: `Revoked machine ${id}. Its key is refused from its next request.` };
+};

package/dist/sessions/machine-hold.d.ts

@@ -0,0 +1,49 @@
+import type { Git } from './survival.js';
+/** What one commit needs: the folder the session ran in and the operator's list (the repository is checked again here), the branch's two names, the three files' contents, and the salt the terms digest is keyed with. */
+export interface HoldInput {
+    cwd: string | undefined;
+    allowRepos: readonly string[];
+    machine: string;
+    id: string;
+    /** The batch's bytes, as the outbox holds them. */
+    batch: string;
+    stamp: string;
+    /** The term list the batch was gated under, as the term file holds it. */
+    terms: readonly string[];
+    /** `OARS_SESSION_SALT`. */
+    salt: string;
+}
+/** The branch a session's batch is held on. The proxy of a cloud session takes branches only, so the namespace is a branch prefix. */
+export declare const holdBranch: (machine: string, id: string) => string;
+/**
+ * `HMAC-SHA-256(salt, list)` in hex, where the list is the terms trimmed and lowercased (as `loadTerms` reads them), blanks dropped, then deduped, sorted, and joined with newlines: one list gives one digest in any order, case, or
+ * blank lines. It is keyed so that a reader of the branch cannot test a guessed term against it; it detects a stale list, not a forged one, since the VM holds the salt and the list both.
+ */
+export declare const termsDigest: (salt: string, terms: readonly string[]) => string;
+/**
+ * Commits the batch to a tree of its own and returns the commit's sha, or `undefined` when the repository is not on the operator's list now: a batch whose repository left `OARS_ALLOW_REPOS` after it was built is not committed.
+ * Nothing but objects is written (no ref, no `HEAD`, no index, no file), and the commit's message says `[skip ci]`, so a hold push starts no workflow. `parent` is the branch's tip when it has one.
+ */
+export declare const holdCommit: (git: Git, input: HoldInput, parent?: string) => Promise<string | undefined>;
+/**
+ * Runs one git command that talks to a remote (`push`, `fetch`), with the transports a remote needs (`runGit` allows none) and no terminal prompt, so a missing credential fails the push instead of asking. Rejects on any non-zero exit;
+ * the message is kept for the caller's own use and is never logged by this module, since a remote's error text can carry its URL.
+ */
+export declare const runNetGit: Git;
+export interface HoldDeps {
+    /** Local plumbing and the `origin` URL read (`runGit`, which allows no transport). */
+    git: Git;
+    /** Push and fetch (`runNetGit`). */
+    net: Git;
+    /** One line in the step log, for a push that was refused every time. */
+    log: (error: unknown) => Promise<void>;
+}
+export type HoldResult = 'pushed' | 'refused' | 'skipped';
+/** A refused push is tried again on top of the branch's fetched tip, three attempts in all. */
+export declare const HOLD_ATTEMPTS = 3;
+/**
+ * Commits the batch (`holdCommit`) and pushes it to `oars-hold/<machine>/<id>`. The first push builds on the tip this VM last knew, so a session's later turns are fast-forwards. A refused push is treated as refused whatever the reason, and its message is not read:
+ * the child fetches the branch's tip (an earlier VM of the session may have moved it), commits again on top of it, and pushes, up to three attempts in all. A third refusal writes one log row and returns `refused`; the batch stays in the outbox
+ * and the next Stop rebuilds the session whole. `skipped` is a repository that is not on the operator's list now, or a session with no folder. Nothing here throws for a refusal.
+ */
+export declare const holdBatch: (deps: HoldDeps, input: HoldInput) => Promise<HoldResult>;

package/dist/sessions/machine-hold.js

@@ -0,0 +1,88 @@
+// The holding route of a machine, the VM side: a cloud VM keeps its deposit in its own private repository. Each batch the machine child builds is committed to the branch `oars-hold/<machine>/<id>` with git plumbing
+// (`hash-object`, `mktree`, `commit-tree`), so the session's `HEAD`, index, and working tree are never touched, and the commit is pushed from there (`holdBatch`, below). The commit holds three files: `batch.json` (the batch
+// as `oars pool outbox` prints it), `stamp` (the client's batch stamp), and `terms` (a keyed digest of the exclusion terms the batch was gated under, so a reader with another list can tell). Admission is the trusted side's.
+import { execFile } from 'node:child_process';
+import { createHmac } from 'node:crypto';
+import { repoAllowed } from './machine-repo.js';
+/** The branch a session's batch is held on. The proxy of a cloud session takes branches only, so the namespace is a branch prefix. */
+export const holdBranch = (machine, id) => `oars-hold/${machine}/${id}`;
+/**
+ * `HMAC-SHA-256(salt, list)` in hex, where the list is the terms trimmed and lowercased (as `loadTerms` reads them), blanks dropped, then deduped, sorted, and joined with newlines: one list gives one digest in any order, case, or
+ * blank lines. It is keyed so that a reader of the branch cannot test a guessed term against it; it detects a stale list, not a forged one, since the VM holds the salt and the list both.
+ */
+export const termsDigest = (salt, terms) => {
+    const list = [...new Set(terms.map((term) => term.trim().toLowerCase()).filter((term) => term !== ''))].sort().join('\n');
+    return createHmac('sha256', salt).update(list).digest('hex');
+};
+// A hold commit is made by oars, not by the person: its own identity, and no signing, so a VM with no `user.name` or a signing key set globally still commits.
+const IDENTITY = ['-c', 'user.name=oars', '-c', 'user.email=oars@users.noreply.github.com', '-c', 'commit.gpgsign=false'];
+/** Writes `content` as a blob exactly as given: `--no-filters`, so a repository's line-ending settings cannot change the batch's bytes. */
+const blobOf = async (git, cwd, content) => (await git(cwd, ['hash-object', '-w', '--no-filters', '--stdin'], content)).trim();
+/**
+ * Commits the batch to a tree of its own and returns the commit's sha, or `undefined` when the repository is not on the operator's list now: a batch whose repository left `OARS_ALLOW_REPOS` after it was built is not committed.
+ * Nothing but objects is written (no ref, no `HEAD`, no index, no file), and the commit's message says `[skip ci]`, so a hold push starts no workflow. `parent` is the branch's tip when it has one.
+ */
+export const holdCommit = async (git, input, parent) => {
+    if (input.cwd === undefined || !(await repoAllowed(input.allowRepos, input.cwd, git)))
+        return undefined;
+    const files = [
+        ['batch.json', input.batch],
+        ['stamp', `${input.stamp}\n`],
+        ['terms', `${termsDigest(input.salt, input.terms)}\n`],
+    ];
+    const entries = [];
+    for (const [name, content] of files)
+        entries.push(`100644 blob ${await blobOf(git, input.cwd, content)}\t${name}\n`);
+    const tree = (await git(input.cwd, ['mktree'], entries.join(''))).trim();
+    const message = `oars hold ${input.id} [skip ci]`;
+    return (await git(input.cwd, [...IDENTITY, 'commit-tree', tree, ...(parent === undefined ? [] : ['-p', parent]), '-m', message])).trim();
+};
+/** Where a push or a fetch may wait: the cloud proxy answers a push in seconds, and a hung one must not hold the child's lock for good. */
+const NET_TIMEOUT_MS = 120_000;
+/**
+ * Runs one git command that talks to a remote (`push`, `fetch`), with the transports a remote needs (`runGit` allows none) and no terminal prompt, so a missing credential fails the push instead of asking. Rejects on any non-zero exit;
+ * the message is kept for the caller's own use and is never logged by this module, since a remote's error text can carry its URL.
+ */
+export const runNetGit = (root, args) => new Promise((resolve, reject) => {
+    execFile('git', ['-C', root, ...args], { encoding: 'utf8', timeout: NET_TIMEOUT_MS, windowsHide: true, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_DIR: undefined, GIT_WORK_TREE: undefined, GIT_INDEX_FILE: undefined } }, (error, stdout) => {
+        if (error === null)
+            resolve(stdout);
+        else
+            reject(new Error(error.message));
+    });
+});
+/** A refused push is tried again on top of the branch's fetched tip, three attempts in all. */
+export const HOLD_ATTEMPTS = 3;
+/** The branch's last known tip, kept under a private ref that no checkout shows (`git branch` lists `refs/heads` only): the commit this VM pushed last, or the tip a refused push fetched. */
+const tipOf = async (git, cwd, seen) => (await git(cwd, ['rev-parse', '--verify', '--quiet', `${seen}^{commit}`]).catch(() => '')).trim() || undefined;
+/**
+ * Commits the batch (`holdCommit`) and pushes it to `oars-hold/<machine>/<id>`. The first push builds on the tip this VM last knew, so a session's later turns are fast-forwards. A refused push is treated as refused whatever the reason, and its message is not read:
+ * the child fetches the branch's tip (an earlier VM of the session may have moved it), commits again on top of it, and pushes, up to three attempts in all. A third refusal writes one log row and returns `refused`; the batch stays in the outbox
+ * and the next Stop rebuilds the session whole. `skipped` is a repository that is not on the operator's list now, or a session with no folder. Nothing here throws for a refusal.
+ */
+export const holdBatch = async (deps, input) => {
+    const cwd = input.cwd;
+    if (cwd === undefined)
+        return 'skipped';
+    const branch = holdBranch(input.machine, input.id);
+    const seen = `refs/oars-hold/${input.machine}/${input.id}`;
+    let parent = await tipOf(deps.git, cwd, seen);
+    for (let attempt = 1; attempt <= HOLD_ATTEMPTS; attempt += 1) {
+        const commit = await holdCommit(deps.git, input, parent);
+        if (commit === undefined)
+            return 'skipped';
+        // `--no-verify`: the session repository's own `pre-push` hook (husky, or a `core.hooksPath` its install step set) is the project's, not ours, and could run its checks at every Stop under the send lock or refuse every hold push, losing the batch with the VM.
+        const accepted = await deps.net(cwd, ['push', '--no-verify', 'origin', `${commit}:refs/heads/${branch}`]).then(() => true, () => false);
+        if (accepted) {
+            // Bookkeeping only: a failure here must not turn an accepted push into a retry.
+            await deps.git(cwd, ['update-ref', seen, commit]).catch(() => undefined);
+            return 'pushed';
+        }
+        if (attempt < HOLD_ATTEMPTS) {
+            await deps.net(cwd, ['fetch', '--quiet', 'origin', `+refs/heads/${branch}:${seen}`]).catch(() => undefined);
+            parent = (await tipOf(deps.git, cwd, seen)) ?? parent;
+        }
+    }
+    await deps.log(new Error(`a hold push of ${branch} was refused ${String(HOLD_ATTEMPTS)} times; the batch stays in the outbox`));
+    return 'refused';
+};

package/dist/sessions/machine-ids.d.ts

@@ -0,0 +1,6 @@
+/** The salt a purpose gets: `repoKey/1` keys a repository's hash, `sessionId/1` a machine's session ids. A derived salt computes that one hash and nothing else, so it can leave the trusted machine and the store salt cannot. */
+export declare const derivedSalt: (localSalt: string, purpose: "repoKey/1" | "sessionId/1") => string;
+/** A session's name without the prefix the cloud puts on it: the variable carries `cse_`, the id a teleport takes carries `session_`, and unstripped the two would hash apart and one session would count twice. */
+export declare const sessionName: (session: string) => string;
+/** The skeleton `id` of a machine's session: the first 16 hex digits of the session's HMAC under the environment's session salt, the one shape the wire and the outbox accept. */
+export declare const machineIdOf: (sessionSalt: string, session: string) => string;

package/dist/sessions/machine-ids.js

@@ -0,0 +1,9 @@
+// The two keyed values a machine and its trusted machine must compute the same way: the salts the enrollment derives from the store salt, and the skeleton `id` of a session a machine holds. Only node:crypto, so the
+// Stop hook's child pays for no pool module to read them.
+import { createHmac } from 'node:crypto';
+/** The salt a purpose gets: `repoKey/1` keys a repository's hash, `sessionId/1` a machine's session ids. A derived salt computes that one hash and nothing else, so it can leave the trusted machine and the store salt cannot. */
+export const derivedSalt = (localSalt, purpose) => createHmac('sha256', localSalt).update(purpose).digest('hex');
+/** A session's name without the prefix the cloud puts on it: the variable carries `cse_`, the id a teleport takes carries `session_`, and unstripped the two would hash apart and one session would count twice. */
+export const sessionName = (session) => session.replace(/^(?:cse_|session_)/u, '');
+/** The skeleton `id` of a machine's session: the first 16 hex digits of the session's HMAC under the environment's session salt, the one shape the wire and the outbox accept. */
+export const machineIdOf = (sessionSalt, session) => createHmac('sha256', sessionSalt).update(sessionName(session)).digest('hex').slice(0, 16);

package/dist/sessions/machine-notice.d.ts

@@ -0,0 +1,21 @@
+export declare const NOTICE_CODES: readonly ["vocabulary_expired", "hold_unconfigured", "machine_key_expiring", "machine_key_expired", "machine_key_revoked", "machine_key_retired", "machine_key_unknown"];
+export type NoticeCode = (typeof NOTICE_CODES)[number];
+export interface NoticeEntry {
+    code: NoticeCode;
+    /** Epoch milliseconds when the child wrote it. */
+    at: number;
+    /** Epoch milliseconds the machine key expires, kept for `machine_key_expiring` so the message can name the day. */
+    expiresAt?: number;
+}
+/** A code is written at most this often, so an expired client prints its message once a day, not at every Stop. */
+export declare const NOTICE_INTERVAL_MS: number;
+export declare const noticeFile: (storeDir: string) => string;
+/** The child records a condition: its entry replaces an earlier one of the same code and keeps its place, so the file lists the codes in the order they were first raised. A notice file it cannot read is rewritten. */
+export declare const recordNotice: (storeDir: string, code: NoticeCode, at: number, expiresAt?: number) => Promise<void>;
+/** The one message for a set of entries, or `undefined` for none. */
+export declare const messageOf: (entries: readonly NoticeEntry[]) => string | undefined;
+/**
+ * The Stop reads the notice and clears it: the file is renamed first, so two Stops never both print it, then read and removed. The text, or `undefined` when there is no notice. Never throws: a hook that cannot read its notice goes on to
+ * start its child, and the condition, still true, is written again by that child.
+ */
+export declare const takeNotice: (storeDir: string) => string | undefined;