@manyoars/oars 0.4.1 → 0.5.2

package/dist/sessions/machine-notice.js

@@ -0,0 +1,89 @@
+// The notice file of a machine: the one way the detached child tells the person anything. A child prints to nowhere (its output is redirected, and its Stop has long returned), so a condition the person has to act on is written here, and the
+// next Stop reads the file before it starts its own child and prints it once, as the hook's `systemMessage`. The file is `<store>/machine-notice.json`, `{"entries":[{"code":"vocabulary_expired","at":<ms>}]}`, one entry per code
+// (a repeat replaces its entry, so a condition that holds at every Stop is one line, not a pile). `vocabulary_expired` is the first code: a client past its vocabulary's age builds no batch, and its sessions wait.
+// The reader runs inside the Stop hook, so it is synchronous and reads only this one small file.
+import { readFileSync, renameSync, rmSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { mkdirOwnerOnly, writeOwnerOnly } from './owner-only.js';
+export const NOTICE_CODES = ['vocabulary_expired', 'hold_unconfigured', 'machine_key_expiring', 'machine_key_expired', 'machine_key_revoked', 'machine_key_retired', 'machine_key_unknown'];
+const NOTICE = 'machine-notice.json';
+// When each code was last written: the notice file is cleared when a Stop prints it, so the cap needs a record that outlives it.
+const WRITTEN = 'machine-notified.json';
+/** A code is written at most this often, so an expired client prints its message once a day, not at every Stop. */
+export const NOTICE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export const noticeFile = (storeDir) => join(storeDir, NOTICE);
+/** What the person is told for each code: what stopped, what is kept, and the one step. */
+const LIST = 'oars pool machines lists the machines of your account, their expiry included.';
+const TEXT = {
+    hold_unconfigured: () => 'oars on this machine holds nothing: OARS_MACHINE or OARS_SESSION_SALT is missing from its enrollment, so no session reaches its hold branch and the data of its sessions is lost. Run oars pool enroll --hold-only on your own machine and set the printed block in this environment.',
+    vocabulary_expired: () => 'oars on this machine is out of date, so it builds no deposit batches: its closed vocabulary is past its age limit. The sessions stay on this machine. Upgrade with npm install -g @manyoars/oars.',
+    machine_key_expiring: (entry) => `The pool key of this machine expires ${entry.expiresAt === undefined ? 'soon' : `on ${new Date(entry.expiresAt).toISOString().slice(0, 10)}`}; after that its deposits are refused. ${LIST} Enroll the machine again with oars pool enroll before then.`,
+    machine_key_expired: () => `The pool key of this machine has expired, so its deposits are refused and its batches wait in its outbox. ${LIST} Enroll the machine again with oars pool enroll.`,
+    machine_key_revoked: () => 'The account revoked the pool key of this machine, so its deposits are refused and its batches wait in its outbox. See oars pool machines; enroll this machine again with oars pool enroll if the revocation was a mistake.',
+    machine_key_retired: () => `The pool key of this machine was replaced by a rotation that did not finish on this machine, so the pool refuses what is left of it and its batches wait in its outbox. ${LIST} Enroll the machine again with oars pool enroll.`,
+    machine_key_unknown: () => `The pool does not know the credential this machine presents, so its deposits are refused and its batches wait in its outbox. Check the network secret (cloud) or the key file (other machines), or enroll the machine again; ${LIST} If this machine is hold-only, set OARS_HOLD_ONLY=1.`,
+};
+const isCode = (value) => NOTICE_CODES.some((code) => code === value);
+/** The entries in `text`, those with a known code and a numeric time; anything else in the file (a newer client's code, a damaged line) is dropped. */
+const entriesOf = (text) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    const listed = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'entries') : undefined;
+    if (!Array.isArray(listed))
+        return [];
+    return listed.flatMap((entry) => {
+        const code = typeof entry === 'object' && entry !== null ? Reflect.get(entry, 'code') : undefined;
+        const at = typeof entry === 'object' && entry !== null ? Reflect.get(entry, 'at') : undefined;
+        const expiresAt = typeof entry === 'object' && entry !== null ? Reflect.get(entry, 'expiresAt') : undefined;
+        return isCode(code) && typeof at === 'number' ? [{ code, at, ...(typeof expiresAt === 'number' ? { expiresAt } : {}) }] : [];
+    });
+};
+/** 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 const recordNotice = async (storeDir, code, at, expiresAt) => {
+    const written = entriesOf(await readFile(join(storeDir, WRITTEN), 'utf8').catch(() => ''));
+    const last = written.find((entry) => entry.code === code);
+    // A clock that moved backward (`at < last.at`) writes again, rather than staying quiet until it catches up.
+    if (last !== undefined && at >= last.at && at - last.at < NOTICE_INTERVAL_MS)
+        return;
+    const kept = entriesOf(await readFile(noticeFile(storeDir), 'utf8').catch(() => ''));
+    // A Map keeps a key's first place when it is set again.
+    const byCode = new Map(kept.map((entry) => [entry.code, entry]));
+    // A key that is expired or revoked is no longer "expiring": one message must not say both.
+    if (code === 'machine_key_expired' || code === 'machine_key_revoked')
+        byCode.delete('machine_key_expiring');
+    byCode.set(code, { code, at, ...(expiresAt === undefined ? {} : { expiresAt }) });
+    const entries = [...byCode.values()];
+    await mkdirOwnerOnly(storeDir);
+    await writeOwnerOnly(noticeFile(storeDir), `${JSON.stringify({ entries })}\n`);
+    await writeOwnerOnly(join(storeDir, WRITTEN), `${JSON.stringify({ entries: [...written.filter((entry) => entry.code !== code), { code, at }] })}\n`);
+};
+/** The one message for a set of entries, or `undefined` for none. */
+export const messageOf = (entries) => (entries.length === 0 ? undefined : entries.map((entry) => TEXT[entry.code](entry)).join(' '));
+/**
+ * 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 const takeNotice = (storeDir) => {
+    const taken = `${noticeFile(storeDir)}.${String(process.pid)}`;
+    try {
+        renameSync(noticeFile(storeDir), taken);
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        return messageOf(entriesOf(readFileSync(taken, 'utf8')));
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        rmSync(taken, { force: true });
+    }
+};

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

@@ -0,0 +1,40 @@
+import type { Outcome, RunDeps } from '../cli.js';
+import { type Visibility } from './machine-enroll.js';
+import { type LockTimes } from './pool-send-lock.js';
+import type { Git } from './survival.js';
+/** What a pull reaches outside the store: GitHub's record of a repository, local git plumbing (`runGit`), git over the network (`runNetGit`), and where a repository is fetched from. */
+export interface PullPorts {
+    visibility: Visibility;
+    git: Git;
+    net: Git;
+    remoteOf: (repo: string) => string;
+    /** The send lock's waits, for a test that cannot sit out the two-minute default. */
+    lock?: Partial<LockTimes>;
+    /** Called as a pull comes to the send lock to write an admitted batch: a test waits on it instead of a sleep. */
+    onLock?: () => void;
+}
+/** Why a repository or a branch was set aside; the report names it, and a test holds each. */
+export type PullReason = 'repo_public' | 'repo_unconfirmed' | 'repo_unreadable' | 'branch_name' | 'unknown_machine' | 'machine_repo' | 'duplicate_id' | 'unreadable_file' | 'batch_invalid' | 'id_mismatch' | 'stamp_invalid' | 'terms_stale' | 'differing_stamp' | 'field_unknown' | 'claimed_present' | 'off_list' | 'a38_term' | 'machine_record';
+/** A repository (no `branch`) or a branch that was refused, and why. */
+export interface PullRefusal {
+    repo: string;
+    branch?: string;
+    reason: PullReason;
+    detail: string;
+}
+/** A batch that reached the outbox, under the folder of its stamp. */
+export interface PullAdmission {
+    repo: string;
+    branch: string;
+    id: string;
+    stamp: string;
+    /** Whether the branch is gone from the repository. False when it moved after it was fetched (a newer push is kept and the next pull admits it) or the remote refused the delete; the batch is admitted either way. */
+    branchDeleted: boolean;
+}
+/**
+ * Pulls what every enrolled machine held. Each repository on any machine's list is checked against GitHub's record again on every run, and one that is no longer private is refused and reported, its branches unread. The branches that
+ * remain are taken newest first, and the newest of an `id` alone speaks for it: an older branch of that `id` is reported as a duplicate whether or not the newest was admitted; each branch must name a machine this one enrolled, for that repository.
+ */
+export declare const holdPull: (deps: RunDeps, options: {
+    server?: string | undefined;
+}, ports: PullPorts) => Promise<Outcome>;

package/dist/sessions/machine-pull.js

@@ -0,0 +1,220 @@
+// `oars pool hold pull`: admission of the batches a cloud VM held on `oars-hold/<machine>/<id>` branches of its own private repository (the VM side is `machine-hold.ts`). The trusted machine does it, and treats every branch as input
+// from outside: anything able to push a branch can write one, the session's own agent included. A branch that fails any gate is reported with its reason, writes nothing to the outbox, and stays where it is; the branch of an admitted batch is deleted
+// from here (the VM's proxy refuses deletions), and only after the batch and its `pulled.json` entry are durable.
+import { mkdtemp, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CliError, ExitCode } from '../errors.js';
+import { exclusionPaths, loadTerms } from './exclusion.js';
+import { termsDigest } from './machine-hold.js';
+import { readMachines } from './machine-enroll.js';
+import { derivedSalt } from './machine-ids.js';
+import { poolServer, runtimeOf } from './pool-command.js';
+import { SendLockBusy, withSendLock } from './pool-send-lock.js';
+import { BATCH_FIELDS, STAMP_FOLDER, currentStamp, fieldsOf, holdsTerm, outboxFolder, readPulled, removeBatchOf, writeBatch, writePulled } from './pool-outbox.js';
+import { CLAIMED_HOST_CLASSES, CLAIMED_LAUNCHERS, parseSkeleton } from './pool-wire.js';
+import { localSalt } from './store.js';
+const STEP = 'pool-hold-pull';
+class Refused extends Error {
+    reason;
+    constructor(reason, detail) {
+        super(detail);
+        this.reason = reason;
+    }
+}
+/** The id is the outbox key, which holds only 16 hex digits (`machineIdOf`), so a branch of any other id is refused by its name, before its file is read. */
+const BRANCH = /^oars-hold\/([^/]+)\/([0-9a-f]{16})$/u;
+/** The branch tips of `oars-hold/*` in one repository, each commit only: depth 1, so history is never fetched, and no tag. The scratch repository is bare and lives under `parent` until the pull ends. */
+const tipsOf = async (ports, parent, repo) => {
+    const scratch = await mkdtemp(join(parent, 'repo-'));
+    await ports.git(scratch, ['init', '--bare', '--quiet']);
+    // A depth-1 fetch of a pattern that matches nothing fails, and with branches deleted as they are admitted that is the usual state of a repository: ask first, and fetch only when a held branch is there.
+    if ((await ports.net(scratch, ['ls-remote', '--heads', ports.remoteOf(repo), 'refs/heads/oars-hold/*'])).trim() === '')
+        return [];
+    await ports.net(scratch, ['fetch', '--quiet', '--no-tags', '--depth=1', ports.remoteOf(repo), '+refs/heads/oars-hold/*:refs/held/*']);
+    const listing = await ports.git(scratch, ['for-each-ref', '--format=%(refname:strip=2)%09%(objectname)%09%(committerdate:unix)', 'refs/held/']);
+    return listing
+        .split('\n')
+        .filter((line) => line !== '')
+        .map((line) => {
+        const [name = '', sha = '', at = '0'] = line.split('\t');
+        return { repo, branch: `oars-hold/${name}`, sha, at: Number(at), scratch };
+    });
+};
+/** A file of the tip's tree, or undefined when the tree has none by that name (or it is not a file). */
+const fileOf = (ports, tip, name) => ports.git(tip.scratch, ['cat-file', 'blob', `${tip.sha}:${name}`]).catch(() => undefined);
+const refusalOf = (tip, error) => {
+    if (error instanceof Refused)
+        return { repo: tip.repo, branch: tip.branch, reason: error.reason, detail: error.message };
+    throw error;
+};
+/** The batch file of a tip as the skeleton the pool's own reader makes of it; throws `Refused` for anything that reader, or the branch's own name, would not take. */
+const skeletonOf = async (run, tip, id) => {
+    const batch = await fileOf(run.ports, tip, 'batch.json');
+    if (batch === undefined)
+        throw new Refused('unreadable_file', 'the branch holds no batch.json');
+    let value;
+    try {
+        value = JSON.parse(batch);
+    }
+    catch {
+        throw new Refused('batch_invalid', 'batch.json is not JSON');
+    }
+    // None of these details repeats a value of the file: a branch is written by whoever could push it, and its text must not reach a log.
+    // `JSON.parse` takes a file nested far deeper than the recursive walks below can follow, and a RangeError out of one of them would end the whole pull.
+    try {
+        const names = fieldsOf(batch);
+        if (names.includes('claimed'))
+            throw new Refused('claimed_present', 'the batch holds a claimed field, which only this machine writes');
+        if (names.some((name) => !BATCH_FIELDS.includes(name)))
+            throw new Refused('field_unknown', 'the batch holds a field outside the batch field list');
+        const parsed = parseSkeleton(value);
+        if (!parsed.ok)
+            throw new Refused('batch_invalid', `${parsed.field}: ${parsed.reason}`);
+        if (parsed.extensions.length > 0)
+            throw new Refused('off_list', `${String(parsed.extensions.length)} value or field off the current lists, at ${parsed.extensions.slice(0, 3).map(({ at }) => at).join(', ')}`);
+        if (parsed.skeleton.id !== id)
+            throw new Refused('id_mismatch', 'the batch names another id than its branch');
+        if (holdsTerm(value, run.list))
+            throw new Refused('a38_term', 'a string or key of the batch holds a term of the exclusion list of this machine');
+        return parsed.skeleton;
+    }
+    catch (error) {
+        if (error instanceof RangeError)
+            throw new Refused('batch_invalid', 'batch.json is nested too deeply');
+        throw error;
+    }
+};
+/** A refusal of a batch built under another stamp is reported as that, with the cause: an older vocabulary or field list is the usual reason a file fails the reader or the closed lists now. */
+const underStamp = async (stamp, work) => {
+    try {
+        return await work();
+    }
+    catch (error) {
+        if (error instanceof Refused && stamp !== currentStamp())
+            throw new Refused('differing_stamp', `${error.reason}: ${error.message}`);
+        throw error;
+    }
+};
+/**
+ * Deletes the branch the batch came from, but only while it still points at the tip that was read: a push that landed since is a newer state of the session and is left for the next pull. The remote's own text is never kept, since it can carry
+ * the remote's URL. Answers whether the branch is gone.
+ */
+const deleteBranch = async (ports, tip) => {
+    try {
+        await ports.net(tip.scratch, ['push', '--quiet', `--force-with-lease=refs/heads/${tip.branch}:${tip.sha}`, ports.remoteOf(tip.repo), `:refs/heads/${tip.branch}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** One tip through its gates; answers the admission, or throws `Refused` with the first gate that failed. Nothing is written before the batch is through every gate. */
+const admit = async (run, tip, id, machine) => {
+    const record = run.machines.find((known) => known.machine === machine);
+    if (record === undefined)
+        throw new Refused('unknown_machine', `no machine ${machine} in machines.jsonl`);
+    if (!record.allowRepos.includes(tip.repo))
+        throw new Refused('machine_repo', `machine ${machine} was not enrolled for ${tip.repo}`);
+    // The claim comes from this machine's own record and nothing the branch holds, so a record the closed lists do not hold admits nothing.
+    const hostClass = CLAIMED_HOST_CLASSES.find((name) => name === record.hostClass);
+    const launcher = CLAIMED_LAUNCHERS.find((name) => name === record.launcher);
+    if (hostClass === undefined || launcher === undefined)
+        throw new Refused('machine_record', `machines.jsonl holds a host class or launcher for machine ${machine} that the closed lists do not`);
+    // The stamp becomes a path segment, so it is checked before anything else of the branch is used.
+    const stamp = (await fileOf(run.ports, tip, 'stamp'))?.trim();
+    if (stamp === undefined || !STAMP_FOLDER.test(stamp))
+        throw new Refused('stamp_invalid', 'the branch holds no stamp, or it is not a stamp folder name');
+    // The compare is made whatever the stamp says: a list that changed since the environment was enrolled keeps every branch of that environment.
+    const held = (await fileOf(run.ports, tip, 'terms'))?.trim();
+    if (held !== run.terms)
+        throw new Refused('terms_stale', held === undefined ? 'the branch holds no terms digest' : 'the branch was gated under another exclusion term list than this machine\'s');
+    const skeleton = await underStamp(stamp, () => skeletonOf(run, tip, id));
+    // The stamp's version names the vocabulary the batch was built under: a file that says otherwise is not what its stamp claims.
+    if (stamp.slice(0, -9) !== `v${skeleton.vocabVersion}`)
+        throw new Refused('stamp_invalid', 'the stamp does not name the batch\'s vocabulary version');
+    // The send lock is held across the writes, because the nightly and `--send` change `pulled.json` and prune the current-stamp folder under it: without it a pass could prune the batch before its entry is written, or write its own read of
+    // `pulled.json` over the new entry. The file is read again inside the lock and only this id is merged. The order is the batch, then pulled.json, then the older copy: a crash between them leaves the next pull to replace the same id.
+    run.ports.onLock?.();
+    await withSendLock(run.outbox, async () => {
+        await writeBatch(run.outbox, id, { ...skeleton, claimed: { hostClass, launcher } }, stamp);
+        const pulled = await readPulled(run.outbox, STEP);
+        pulled[id] = stamp;
+        await writePulled(run.outbox, pulled);
+        for (const folder of await readdir(run.outbox)) {
+            if (folder !== stamp && STAMP_FOLDER.test(folder))
+                await removeBatchOf(run.outbox, id, folder);
+        }
+    }, run.ports.lock);
+    // The lock is let go first, so a waiting send pass is not held up by the network. The batch and `pulled.json` are durable, so the branch is no longer the only copy; a crash before this line leaves it for the next pull to replace the same id.
+    return { repo: tip.repo, branch: tip.branch, id, stamp, branchDeleted: await deleteBranch(run.ports, tip) };
+};
+const summary = (admitted, refused) => [
+    `Admitted ${String(admitted.length)} ${admitted.length === 1 ? 'batch' : 'batches'}; refused ${String(refused.length)}. A refused branch stays where it is; an admitted one is deleted.`,
+    ...admitted.map((entry) => `  admitted ${entry.branch} (${entry.repo}) as ${entry.id} under ${entry.stamp}${entry.branchDeleted ? '' : ' (branch kept: it moved since it was read, or the repository refused the delete)'}`),
+    ...refused.map((entry) => `  refused ${entry.branch ?? 'the repository'} (${entry.repo}): ${entry.reason}: ${entry.detail}`),
+].join('\n');
+/**
+ * Pulls what every enrolled machine held. Each repository on any machine's list is checked against GitHub's record again on every run, and one that is no longer private is refused and reported, its branches unread. The branches that
+ * remain are taken newest first, and the newest of an `id` alone speaks for it: an older branch of that `id` is reported as a duplicate whether or not the newest was admitted; each branch must name a machine this one enrolled, for that repository.
+ */
+export const holdPull = async (deps, options, ports) => {
+    const runtime = runtimeOf(deps);
+    const outbox = outboxFolder(runtime.storeDir, poolServer(deps.env, STEP, options.server));
+    const machines = await readMachines(runtime.storeDir);
+    const repos = [...new Set(machines.flatMap((record) => record.allowRepos))].sort();
+    const admitted = [];
+    const refused = [];
+    if (repos.length === 0)
+        return { document: { ok: true, admitted, refused }, text: 'No machine is enrolled: nothing to pull. oars pool enroll --hold-only enrolls one.' };
+    // An empty term file refuses everything, as the local gate does: a digest of no terms would admit a branch from an environment that held none.
+    const termsFile = exclusionPaths(runtime.projectsRoot, deps.env).terms;
+    const terms = await loadTerms(termsFile);
+    if (terms.length === 0)
+        throw new CliError(`No exclusion terms in ${termsFile}: every branch would be unverifiable. Nothing was fetched.`, ExitCode.USAGE, STEP);
+    const sessionSalt = derivedSalt((await (runtime.accountSalt ?? localSalt)(runtime.storeDir)).salt, 'sessionId/1');
+    // Read once to stop before any fetch when the file is bad; `admit` reads it again under the send lock, where it is changed.
+    await readPulled(outbox, STEP);
+    const scratch = await mkdtemp(join(runtime.storeDir, 'hold-pull-'));
+    try {
+        const tips = [];
+        for (const repo of repos) {
+            const seen = await ports.visibility(repo);
+            if (seen !== 'private') {
+                refused.push({ repo, reason: seen === 'public' ? 'repo_public' : 'repo_unconfirmed', detail: seen === 'public' ? 'the repository is public now: its branches were not read' : 'could not confirm the repository is private (a GH_TOKEN or GITHUB_TOKEN that can read it is needed): its branches were not read' });
+                continue;
+            }
+            try {
+                tips.push(...(await tipsOf(ports, scratch, repo)));
+            }
+            catch {
+                // The git error text carries the command line and the remote's URL, so the report gives a fixed cause instead.
+                refused.push({ repo, reason: 'repo_unreadable', detail: 'its branches could not be fetched (check this machine\'s git credential for the repository)' });
+            }
+        }
+        const run = { ports, outbox, machines, terms: termsDigest(sessionSalt, terms), list: terms };
+        const taken = new Set();
+        for (const tip of [...tips].sort((a, b) => b.at - a.at || (a.branch < b.branch ? -1 : 1))) {
+            try {
+                const named = BRANCH.exec(tip.branch);
+                if (named === null)
+                    throw new Refused('branch_name', 'the branch is not oars-hold/<machine>/<id>');
+                const [, machine = '', id = ''] = named;
+                if (taken.has(id))
+                    throw new Refused('duplicate_id', `a newer branch already supplied ${id}`);
+                // Taken before the gates: the newest tip of an `id` alone speaks for it, so when it is refused an older one is not admitted in its place.
+                taken.add(id);
+                admitted.push(await admit(run, tip, id, machine));
+            }
+            catch (error) {
+                // A night holds the lock across its whole send, so a pull that overlaps a long one can be turned away: what was admitted before stays, and the tips left are read by the next pull.
+                if (error instanceof SendLockBusy)
+                    throw new CliError('Another oars run is sending from this outbox. The batches already admitted stay; the rest were not pulled. Run oars pool hold pull again in a minute.', ExitCode.CONFLICT, STEP, { title: 'Another oars run is sending from this outbox.', code: 'send_locked', status: 409 }, { admitted });
+                refused.push(refusalOf(tip, error));
+            }
+        }
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+    return { document: { ok: true, admitted, refused }, text: summary(admitted, refused) };
+};

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

@@ -0,0 +1,7 @@
+import type { Git } from './survival.js';
+/** `owner/name`, lowercased (GitHub names are case-insensitive), from a GitHub remote URL in any common form; `undefined` for anything else. */
+export declare const repoOf: (url: string) => string | undefined;
+/** The repository `origin` names in `cwd`, or `undefined` when the folder is not a repository, has no `origin`, or names one this cannot read. The URL itself is never returned or logged. */
+export declare const originRepo: (git: Git, cwd: string) => Promise<string | undefined>;
+/** Whether the session's folder is a repository on the allow list (`MachineConfig.allowRepos`, already lowercased). A session that forwarded no folder, or an empty list, allows nothing. */
+export declare const repoAllowed: (allowRepos: readonly string[], cwd: string | undefined, git: Git) => Promise<boolean>;

package/dist/sessions/machine-repo.js

@@ -0,0 +1,30 @@
+// `user[:token]@` is allowed before the host and is never kept: the match below captures the path only, so a credential in a remote URL cannot reach a log or a result.
+const URL_FORM = /^(?:https?|ssh|git):\/\/(?:[^@/\s]+@)?github\.com(?::\d+)?\/([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/iu;
+const SCP_FORM = /^(?:[^@/\s]+@)?github\.com:([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/iu;
+/** `owner/name`, lowercased (GitHub names are case-insensitive), from a GitHub remote URL in any common form; `undefined` for anything else. */
+export const repoOf = (url) => {
+    const found = URL_FORM.exec(url.trim()) ?? SCP_FORM.exec(url.trim());
+    if (found === null)
+        return undefined;
+    const owner = found[1];
+    const name = found[2];
+    if (owner === undefined || name === undefined || /^\.+$/u.test(owner) || /^\.+$/u.test(name))
+        return undefined;
+    return `${owner}/${name}`.toLowerCase();
+};
+/** The repository `origin` names in `cwd`, or `undefined` when the folder is not a repository, has no `origin`, or names one this cannot read. The URL itself is never returned or logged. */
+export const originRepo = async (git, cwd) => {
+    try {
+        return repoOf(await git(cwd, ['remote', 'get-url', 'origin']));
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Whether the session's folder is a repository on the allow list (`MachineConfig.allowRepos`, already lowercased). A session that forwarded no folder, or an empty list, allows nothing. */
+export const repoAllowed = async (allowRepos, cwd, git) => {
+    if (cwd === undefined || allowRepos.length === 0)
+        return false;
+    const repo = await originRepo(git, cwd);
+    return repo !== undefined && allowRepos.includes(repo);
+};

package/dist/sessions/machine-scan-cache.d.ts

@@ -0,0 +1,12 @@
+/** How long a clean verdict of a session this Stop does not build is reused. */
+export declare const SCAN_TTL_MS: number;
+export interface ScanCache {
+    /** Whether this session passed the gate at most `SCAN_TTL_MS` ago, under this term list. */
+    fresh: (project: string, session: string) => boolean;
+    /** Records a pass of the gate now. */
+    note: (project: string, session: string) => void;
+    /** Writes the cache when a pass was noted. */
+    save: () => Promise<void>;
+}
+/** The cache for this term list (`terms` is the list's hash, so a changed list starts empty). An unreadable or damaged file is an empty cache. */
+export declare const scanCache: (storeDir: string, terms: string, now: () => number) => Promise<ScanCache>;

package/dist/sessions/machine-scan-cache.js

@@ -0,0 +1,47 @@
+// What a Stop remembers about the sessions it does not build. A Stop names one session and only reads the others to fill the windows of a delta, but each read is the whole exclusion gate (every transcript, scanned for the terms): measured on a
+// store of 5,000 sessions it was 17.8 s of the 18.6 s a Stop took on Windows. So a session that passed the gate is remembered for ten minutes, per term list: the same list and the same session are not scanned again at the Stop after.
+// A session that gains a term inside the window is still excluded from every batch (the session a Stop builds is always scanned in full); it can only fill a window for ten minutes more. `<store>/machine-scan-cache.json`, owner-only.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { mkdirOwnerOnly, writeOwnerOnly } from './owner-only.js';
+/** How long a clean verdict of a session this Stop does not build is reused. */
+export const SCAN_TTL_MS = 10 * 60 * 1000;
+const FILE = 'machine-scan-cache.json';
+const keyOf = (project, session) => JSON.stringify([project, session]);
+const timesOf = (text, terms) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return new Map();
+    }
+    const same = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'terms') : undefined;
+    const listed = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'passed') : undefined;
+    if (same !== terms || typeof listed !== 'object' || listed === null)
+        return new Map();
+    return new Map(Object.entries(listed).flatMap(([key, at]) => (typeof at === 'number' ? [[key, at]] : [])));
+};
+/** The cache for this term list (`terms` is the list's hash, so a changed list starts empty). An unreadable or damaged file is an empty cache. */
+export const scanCache = async (storeDir, terms, now) => {
+    const passed = timesOf(await readFile(join(storeDir, FILE), 'utf8').catch(() => ''), terms);
+    let changed = false;
+    return {
+        fresh: (project, session) => {
+            const at = passed.get(keyOf(project, session));
+            return at !== undefined && at <= now() && now() - at < SCAN_TTL_MS;
+        },
+        note: (project, session) => {
+            passed.set(keyOf(project, session), now());
+            changed = true;
+        },
+        save: async () => {
+            if (!changed)
+                return;
+            // Entries past their window go: the file never holds more than the sessions of the last ten minutes' Stops.
+            const live = [...passed].filter(([, at]) => at <= now() && now() - at < SCAN_TTL_MS);
+            await mkdirOwnerOnly(storeDir);
+            await writeOwnerOnly(join(storeDir, FILE), `${JSON.stringify({ terms, passed: Object.fromEntries(live) })}\n`);
+        },
+    };
+};

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

@@ -0,0 +1,12 @@
+import type { RunDeps } from '../cli.js';
+import { type Sender } from './pool-command.js';
+/** A key this close to its expiry, or past it, is told to the person. */
+export declare const EXPIRY_NOTICE_MS: number;
+export type MachineSendOutcome = 'not-machine' | 'no-server' | 'no-credential' | 'refused' | 'not-accepted' | 'sent';
+export interface MachineSend {
+    outcome: MachineSendOutcome;
+    /** Batches this run sent. */
+    batches: number;
+}
+/** Activates if needed, checks the covenant, and sends every unsent batch this machine built. Never throws: every failure is a line in `pool-send.log`. */
+export declare const machineSend: (deps: RunDeps, via?: Sender) => Promise<MachineSend>;

package/dist/sessions/machine-send.js

@@ -0,0 +1,156 @@
+// What the machine child does with the pool, after it has built and held a session's batch (`machine-child.ts` calls it under the send lock). First the key: a token is activated (`POST /v1/machines/activate`), and where the disk is durable the pool says to trade it for a fresh key
+// (`/rotate`), which is written owner-only before the token is deleted, so a crash between the two leaves nothing worse than a run that finds the key and deletes the spent token. A cloud machine's token is held by its runtime's proxy and is its key for good. Then, once the covenant
+// is accepted, every unsent batch the machine built goes to the pool (raw never: a machine key deposits none), and the key's expiry, from any answer that carries it or from the refusal of a dead key, is written to the notice file for the next Stop. A refusal is one masked line in
+// `pool-send.log` and leaves the batch unsent; a dead key sends nothing and deletes nothing. No key or token value is ever logged or put in a notice.
+import { rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CliError } from '../errors.js';
+import { credentialOf, keyFile, tokenFile } from './machine-credential.js';
+import { machineOf } from './machine.js';
+import { recordNotice } from './machine-notice.js';
+import { writeOwnerOnly } from './owner-only.js';
+import { ask, DEPOSIT, isObject, networkSender, poolServer, postBatch, refusal, runtimeOf, textIn } from './pool-command.js';
+import { logFailure } from './pool-due.js';
+import { heldAcross, lockedBatch, outboxFolder } from './pool-outbox.js';
+import { markSent, sentHashes } from './pool-sent.js';
+/** A key this close to its expiry, or past it, is told to the person. */
+export const EXPIRY_NOTICE_MS = 14 * 24 * 60 * 60 * 1000;
+/** A cloud VM is new every time, so "activated" is a file in its own store; a durable machine's mark is its key file. */
+const markerOf = (storeDir) => join(storeDir, 'machine-activated');
+const DEAD = { machine_expired: 'machine_key_expired', machine_revoked: 'machine_key_revoked',
+    // A rotation that succeeded at the pool but died before the key was written leaves a retired token and no key.
+    token_retired: 'machine_key_retired',
+    unauthorized: 'machine_key_unknown',
+};
+/** The expiry an answer states, in epoch milliseconds: the deposit and covenant answers carry `machineExpiresAt`, activation the machine's `expiresAt`. A number or a date string. */
+const expiryOf = (body) => {
+    if (!isObject(body))
+        return undefined;
+    const machine = Reflect.get(body, 'machine');
+    const value = Reflect.get(body, 'machineExpiresAt') ?? (isObject(machine) ? Reflect.get(machine, 'expiresAt') : undefined);
+    const at = typeof value === 'string' ? Date.parse(value) : value;
+    return typeof at === 'number' && Number.isFinite(at) ? at : undefined;
+};
+/** Writes the key's state for the next Stop: expired, or expiring within the window; a key with longer to live writes nothing. */
+const noteExpiry = async (storeDir, now, expiresAt) => {
+    if (expiresAt <= now)
+        await recordNotice(storeDir, 'machine_key_expired', now);
+    else if (expiresAt - now <= EXPIRY_NOTICE_MS)
+        await recordNotice(storeDir, 'machine_key_expiring', now, expiresAt);
+};
+/** A sender that notes the expiry any answer states as it passes. */
+const watching = (deps, storeDir, net) => async (request) => {
+    const reply = await net(request);
+    const expiresAt = reply.status < 300 ? expiryOf(reply.body) : undefined;
+    if (expiresAt !== undefined)
+        await noteExpiry(storeDir, deps.now(), expiresAt);
+    return reply;
+};
+/** Whether the pool refused the key itself: that is written for the person, and the caller sends no more. */
+const deadKey = async (run, error) => {
+    const notice = DEAD[error instanceof CliError ? (error.problem.code ?? '') : ''];
+    if (notice === undefined)
+        return false;
+    await recordNotice(run.storeDir, notice, run.deps.now());
+    return true;
+};
+/** A refusal that is logged, and noticed when it names a dead key. */
+const failed = async (run, error) => {
+    await logFailure(run.storeDir, run.deps.now(), error);
+    await deadKey(run, error);
+    return undefined;
+};
+/** Activates a token and, where the pool says so, trades it for a key written owner-only; the token goes after the key is on disk. Returns the credential to send with, or `undefined` when the pool refused. */
+const activated = async (run, hostClass) => {
+    const { deps, server, storeDir, via, credential } = run;
+    if (credential.source === 'key') {
+        // A crash after the key was written and before the token was deleted leaves the token behind; it is spent, so it goes now.
+        await rm(tokenFile(deps.env, storeDir), { force: true });
+        return credential;
+    }
+    if (hostClass === 'cloud' && (await stat(markerOf(storeDir)).then(() => true, () => false)))
+        return credential;
+    const call = credential.token === undefined ? {} : { token: credential.token };
+    const reply = await ask(deps, DEPOSIT, server, '/v1/machines/activate', { ...call, body: {} }, via);
+    if (reply.status !== 200 || !isObject(reply.body)) {
+        return failed(run, refusal(DEPOSIT, reply));
+    }
+    if (Reflect.get(reply.body, 'rotate') !== true) {
+        await writeOwnerOnly(markerOf(storeDir), `${new Date(deps.now()).toISOString()}\n`);
+        return credential;
+    }
+    const traded = await ask(deps, DEPOSIT, server, '/v1/machines/rotate', { ...call, body: {} }, via);
+    const key = traded.status === 200 && isObject(traded.body) ? textIn(traded.body, 'key') : undefined;
+    if (key === undefined)
+        return failed(run, refusal(DEPOSIT, traded));
+    await writeOwnerOnly(keyFile(storeDir), `${key}\n`);
+    await rm(tokenFile(deps.env, storeDir), { force: true });
+    return { source: 'key', token: key };
+};
+/** `OARS_HOLD_ONLY` set to anything but empty, `0`, or `false`: the machine holds its sessions and deposits nothing itself. */
+const isHoldOnly = (env) => !['', '0', 'false'].includes((env.OARS_HOLD_ONLY ?? '').trim().toLowerCase());
+/** A refusal about this one batch (its content), after which the next may still go; anything else (a dead key, a closed pool, an unreachable one) ends the run. */
+const aboutBatch = (error) => error instanceof CliError && [400, 409, 413, 422].includes(error.problem.status ?? 0);
+/** Activates if needed, checks the covenant, and sends every unsent batch this machine built. Never throws: every failure is a line in `pool-send.log`. */
+export const machineSend = async (deps, via) => {
+    const none = (outcome) => ({ outcome, batches: 0 });
+    const machine = machineOf(deps.env);
+    if (machine === undefined)
+        return none('not-machine');
+    const { storeDir } = runtimeOf(deps);
+    try {
+        let server;
+        try {
+            server = poolServer(deps.env, DEPOSIT);
+        }
+        catch {
+            return none('no-server');
+        }
+        // A hold-only enrollment has no pool key to present; `OARS_HOLD_ONLY` says so, and every other cloud 401 is reported.
+        if (isHoldOnly(deps.env))
+            return none('no-credential');
+        const first = await credentialOf(machine.hostClass, deps.env, storeDir);
+        if (first === undefined)
+            return none('no-credential');
+        const net = watching(deps, storeDir, via ?? networkSender(deps, DEPOSIT));
+        const credential = await activated({ deps, server, storeDir, via: net, credential: first }, machine.hostClass);
+        if (credential === undefined)
+            return none('refused');
+        const run = { deps, server, storeDir, via: net, credential };
+        const { token } = credential;
+        const covenant = await ask(deps, DEPOSIT, server, '/v1/covenant', token === undefined ? {} : { token }, net);
+        if (covenant.status !== 200 || !isObject(covenant.body)) {
+            await failed(run, refusal(DEPOSIT, covenant));
+            return none('refused');
+        }
+        if (Reflect.get(covenant.body, 'accepted') !== true)
+            return none('not-accepted');
+        const outbox = outboxFolder(storeDir, server);
+        const done = await sentHashes(outbox);
+        const result = none('sent');
+        for (const batch of (await heldAcross(outbox)).batches) {
+            // A batch `hold pull` admitted is the trusted machine's to rescan against its terms and send; this machine's own are sent as built.
+            if (done.has(batch.hash) || batch.pulled)
+                continue;
+            const locked = await lockedBatch(outbox, batch.hash, { requireShown: false, stamp: batch.stamp });
+            if (!locked.ok)
+                continue;
+            try {
+                await postBatch(deps, { server, token, bytes: locked.bytes, hash: batch.hash, via: net });
+            }
+            catch (error) {
+                await failed(run, error);
+                if (aboutBatch(error))
+                    continue;
+                return { ...result, outcome: 'refused' };
+            }
+            await markSent(outbox, batch.hash, deps.now());
+            result.batches += 1;
+        }
+        return result;
+    }
+    catch (error) {
+        await logFailure(storeDir, deps.now(), error);
+        return none('refused');
+    }
+};