@orkestrel/scaffold 0.0.108 → 0.0.109

package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js

@@ -1,37 +1,92 @@
-// Journaled launch of a bench exec or any command that outlives a turn. Run from the checkout root:
-//   node .agents/skills/orkestrel-dispatch/scripts/launch.ts --journal tmp/codex/UNIT.jsonl --errors tmp/codex/UNIT.err --cap 1500 [--status] -- codex exec --json ...
-// The command's stdout goes to --journal and its stderr to --errors; stdin is closed. Arguments after
-// `--` pass to the command verbatim, so no shell quoting is involved. --cap is in seconds: when it
-// expires the process tree is killed and the errors file records `capped=true`. A fractional cap
-// truncates to whole milliseconds, with 1 ms the least. --status records
-// `git status --porcelain` before and after beside the journal, which is how a read-only lane's
-// containment is checked. Stdout carries up to two JSON lines. The spawn line
-// `{"pid","journal","errors"}` prints as soon as the command starts, and the pid, as decimal digits
-// and a newline, goes to `<journal>.pid`. A pid file an earlier run left on the same journal is
-// removed before the spawn, so neither appears when the command cannot start. The summary line
-// prints last, after the command exits, and the errors file ends with `exit=<code>`. At the cap,
-// Windows kills the process tree; any other host kills the command alone, not its descendants.
-// The launcher's own flags are read before `--` alone. Exit: the command's code; 124 when capped;
-// 127 when the command could not start (the errors file names why); 64 on usage, including a
-// journal and errors path that are the same file and a cap that is not a number of seconds from 0
-// to 2147483.
 import { spawn, spawnSync } from 'node:child_process';
-import { appendFileSync, closeSync, mkdirSync, openSync, rmSync, writeFileSync } from 'node:fs';
+import { appendFileSync, closeSync, mkdirSync, openSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
 import { dirname } from 'node:path';
-import { readMissingFlags, readOption } from "./helpers.js";
-// The longest wait a Node timer holds is 2147483647 ms; floored to whole seconds, a longer cap would
-// throw from `AbortSignal.timeout` after the spawn or clamp to 1 ms and kill the command at once.
-const MAX_CAP_SECONDS = 2_147_483;
-// `AbortSignal.timeout` throws on a fractional delay, which `setTimeout` truncates and raises to 1 ms
-// from below, so the cap takes that form before the command starts.
-function computeCapMilliseconds(cap) {
+/**
+ * Holds the longest cap in whole seconds.
+ *
+ * @remarks
+ * The longest wait a Node timer holds is 2147483647 ms; floored to whole seconds, a longer cap would
+ * throw from `AbortSignal.timeout` after the spawn or clamp to 1 ms and kill the command at once.
+ */
+export const MAX_CAP_SECONDS = 2_147_483;
+/** Lists the flags that take a value. */
+export const VALUE_FLAGS = ['--journal', '--errors', '--cap'];
+/** Lists every flag the launcher reads before the separator, value flags and switches alike. */
+export const FLAGS = [...VALUE_FLAGS, '--status'];
+/**
+ * Reads the value that follows a flag.
+ *
+ * @remarks
+ * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
+ * and the `--flag=value` form is not read.
+ *
+ * @param argv - The arguments after the script path.
+ * @param name - The flag, such as `--journal`.
+ * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
+ * another flag.
+ */
+export function readOption(argv, name) {
+    const index = argv.indexOf(name);
+    const value = index === -1 ? undefined : argv[index + 1];
+    return value === undefined || value.startsWith('--') ? undefined : value;
+}
+/**
+ * Names the value flags a caller gave with no value.
+ *
+ * @param argv - The arguments after the script path.
+ * @param names - The flags that take a value.
+ * @returns Each named flag that appears last or is followed by another flag, in argument order.
+ */
+export function readMissingFlags(argv, names) {
+    return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
+}
+/**
+ * Names the flags a caller gave that the script does not read.
+ *
+ * @remarks
+ * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
+ * scan, so the command after it keeps every argument.
+ *
+ * @param argv - The arguments after the script path.
+ * @param flags - Every flag the script reads, value flags and switches alike.
+ * @returns Each argument that opens with `--` and is not a read flag, in argument order.
+ */
+export function readUnknownFlags(argv, flags) {
+    const end = argv.indexOf('--');
+    return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
+}
+/**
+ * Computes the cap in whole milliseconds that the timer takes.
+ *
+ * @remarks
+ * `AbortSignal.timeout` throws on a fractional delay, which `setTimeout` truncates and raises to 1 ms
+ * from below, so the cap takes that form before the command starts.
+ *
+ * @param cap - The cap in seconds.
+ * @returns The whole milliseconds, at least 1.
+ */
+export function computeCapMilliseconds(cap) {
     return Math.max(1, Math.trunc(cap * 1000));
 }
-function readStatus() {
-    const result = spawnSync('git', ['status', '--porcelain'], { encoding: 'utf8' });
+/**
+ * Reads the working tree's `git status --porcelain` output.
+ *
+ * @param cwd - The directory to read the status in. Default: the current directory.
+ * @returns The porcelain text, or a `git status failed:` line carrying git's own message.
+ */
+export function readGitStatus(cwd) {
+    const result = spawnSync('git', ['status', '--porcelain'], {
+        encoding: 'utf8',
+        ...(cwd === undefined ? {} : { cwd }),
+    });
     return result.status === 0 ? result.stdout : `git status failed: ${result.stderr}`;
 }
-function killTree(pid) {
+/**
+ * Kills a process and every process it started, at once and without a chance to clean up.
+ *
+ * @param pid - The process to kill. A process that is already gone is not an error.
+ */
+export function forceKillTree(pid) {
     if (process.platform === 'win32') {
         spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
         return;
@@ -41,7 +96,33 @@ function killTree(pid) {
     }
     catch { }
 }
-function startCommand(command, args, journal, errors) {
+/**
+ * Ends a command that is still running and aborts the controller to say the cap ended it.
+ *
+ * @remarks
+ * The cap's timer cannot be cleared, so it can elapse after the command exited on its own. The
+ * controller aborts only when the command is still running at that moment, which is how the run
+ * records that the cap, and not the command, ended it; a reused pid is never this command's.
+ *
+ * @param child - The running command.
+ * @param ended - The controller that aborts when the cap ended the command.
+ */
+export function endRunning(child, ended) {
+    if (child.pid !== undefined && child.exitCode === null && child.signalCode === null) {
+        ended.abort();
+        forceKillTree(child.pid);
+    }
+}
+/**
+ * Starts the command with its output sent to the journal and errors files.
+ *
+ * @param command - The executable.
+ * @param args - The command's arguments, passed verbatim.
+ * @param journal - The open journal file descriptor that receives stdout.
+ * @param errors - The open errors file descriptor that receives stderr.
+ * @returns The child process, or the failure when the spawn throws.
+ */
+export function startCommand(command, args, journal, errors) {
     try {
         return spawn(command, args, { stdio: ['ignore', journal, errors], windowsHide: true });
     }
@@ -53,16 +134,33 @@ function startCommand(command, args, journal, errors) {
         };
     }
 }
-function waitForExit(child) {
+/**
+ * Waits for a started command to close.
+ *
+ * @param child - The started command.
+ * @returns How it ended: its code and signal, or the error that stopped it.
+ */
+export function waitForExit(child) {
     return new Promise((resolve) => {
         child.on('error', (error) => resolve({ code: null, signal: null, error: error.message }));
         child.on('close', (code, signal) => resolve({ code, signal, error: undefined }));
     });
 }
-async function main(argv) {
+/**
+ * Runs the launcher on its arguments.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The exit code: the command's, 124 when capped, 127 when it could not start, 64 on usage.
+ */
+export async function main(argv) {
     const separator = argv.indexOf('--');
     // The launcher's own flags end at the separator; everything after it belongs to the command.
     const own = separator === -1 ? argv : argv.slice(0, separator);
+    const unknown = readUnknownFlags(argv, FLAGS);
+    if (unknown.length > 0) {
+        console.error(`launch: ${unknown.join(', ')} is not a flag this launcher reads before --; flags: ${FLAGS.join(' ')}`);
+        return 64;
+    }
     const journal = readOption(own, '--journal');
     const errors = readOption(own, '--errors');
     const cap = readMissingFlags(own, ['--cap']).length > 0
@@ -86,7 +184,7 @@ async function main(argv) {
     mkdirSync(dirname(journal), { recursive: true });
     mkdirSync(dirname(errors), { recursive: true });
     if (status)
-        writeFileSync(`${journal}.status-before.txt`, readStatus());
+        writeFileSync(`${journal}.status-before.txt`, readGitStatus());
     const journalFd = openSync(journal, 'w');
     const errorsFd = openSync(errors, 'w');
     rmSync(`${journal}.pid`, { force: true });
@@ -97,25 +195,24 @@ async function main(argv) {
         writeFileSync(`${journal}.pid`, `${child.pid}\n`);
         console.log(JSON.stringify({ pid: child.pid, journal, errors }));
     }
-    // The signal aborts once the cap elapses, so whether it aborted is whether the cap ended the run.
-    // The timer cannot be cleared, so a cap that elapses after the child exited kills nothing: a
-    // reused pid is not this command's.
+    // The ended controller aborts only when the cap found the command still running, so whether it
+    // aborted is whether the cap ended the run.
+    const ended = new AbortController();
     const deadline = child === undefined || capMilliseconds === undefined
         ? undefined
         : AbortSignal.timeout(capMilliseconds);
     deadline?.addEventListener('abort', () => {
-        if (child?.pid !== undefined && child.exitCode === null && child.signalCode === null) {
-            killTree(child.pid);
-        }
+        if (child !== undefined)
+            endRunning(child, ended);
     }, { once: true });
     const exit = 'error' in launched ? launched : await waitForExit(launched);
-    const capped = deadline?.aborted === true;
+    const capped = ended.signal.aborted;
     closeSync(journalFd);
     closeSync(errorsFd);
     const durationMs = Date.now() - started;
     appendFileSync(errors, `${exit.error === undefined ? '' : `launch: the command could not start: ${exit.error}\n`}\nexit=${exit.error === undefined ? (exit.code ?? 'null') : '127'} signal=${exit.signal ?? 'none'} capped=${capped} duration_ms=${durationMs}\n`);
     if (status)
-        writeFileSync(`${journal}.status-after.txt`, readStatus());
+        writeFileSync(`${journal}.status-after.txt`, readGitStatus());
     console.log(JSON.stringify({
         pid: child?.pid,
         exit: exit.error === undefined ? exit.code : 127,
@@ -130,6 +227,8 @@ async function main(argv) {
         return 127;
     return capped ? 124 : (exit.code ?? 1);
 }
-main(process.argv.slice(2)).then((code) => {
-    process.exitCode = code;
-});
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename) {
+    main(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    });
+}

package/dist/agents/skills/orkestrel-dispatch/scripts/login.js

@@ -1,26 +1,139 @@
 // Recover a bench login. Run from the checkout root:
 //   node .agents/skills/orkestrel-dispatch/scripts/login.ts --codex [--cap SECONDS]
 //   node .agents/skills/orkestrel-dispatch/scripts/login.ts --claude
-// --codex reads `codex login status`; when it reports no login, the script runs
-// `codex login --device-auth` with its output journaled to tmp/codex/login.log, prints the
-// verification URL and the one-time code the moment the journal carries them, polls
-// `codex login status` every 5 seconds until it answers or the cap (default 600 seconds) ends, then
-// kills the login by its pid. --claude reads `claude auth status` and prints it. The JSON summary
-// carries `live`; exit 0 when the bench is logged in, 3 when it is not, 64 on usage.
+// --codex reads `codex login status`; a Codex that cannot start reports live false at once. When the
+// status reports no login, the script runs `codex login --device-auth` with its output journaled to
+// tmp/codex/login.log, prints the verification URL and the one-time code the moment the journal
+// carries them, polls `codex login status` every 5 seconds until it answers or the cap (default 600
+// seconds) ends, then kills the login by its pid. Each status read gets the time left to the cap
+// and is ended when it passes. --cap is a number of seconds above 0 and at most 2147483, checked
+// before anything starts.
+// --claude reads `claude auth status` and prints it. Name one bench per run; the script refuses a
+// flag it does not read, the `--flag=value` form included. The JSON summary carries `live`; exit 0
+// when the bench is logged in, 3 when it is not, 64 on usage.
 import { spawn, spawnSync } from 'node:child_process';
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync } from 'node:fs';
-import { readMissingFlags, readOption } from "./helpers.js";
-const JOURNAL = 'tmp/codex/login.log';
-const POLL_MS = 5_000;
-const URL_PATTERN = /https?:\/\/[^\s"'<>]+/u;
-const CODE_PATTERN = /\b([A-Z0-9]{4,5}-[A-Z0-9]{4,5})\b/u;
-function readStatus(command, args) {
-    const result = spawnSync(command, args, { encoding: 'utf8', windowsHide: true });
-    if (result.error !== undefined)
-        return { live: false, text: `${command} could not start: ${result.error.message}` };
-    return { live: result.status === 0, text: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim() };
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** Names the file that journals the device-auth login output. */
+export const JOURNAL = 'tmp/codex/login.log';
+/** Holds the milliseconds between two reads of the login status. */
+export const POLL_MS = 5_000;
+/** Holds the seconds the poll runs when the call gives no cap. */
+export const DEFAULT_CAP = 600;
+/** Holds the longest cap in whole seconds, so the cap in milliseconds stays a finite timer value. */
+export const MAX_CAP_SECONDS = 2_147_483;
+/** Holds the fewest milliseconds one status read gets, so a read that starts at the cap can still answer. */
+export const STATUS_GRACE_MS = 1_000;
+/** Matches the verification URL the login prints. */
+export const URL_PATTERN = /https?:\/\/[^\s"'<>]+/u;
+/** Matches the one-time code the login prints, such as `ABCD-12345`. */
+export const CODE_PATTERN = /\b([A-Z0-9]{4,5}-[A-Z0-9]{4,5})\b/u;
+/** Lists the flags that take a value. */
+export const VALUE_FLAGS = ['--cap'];
+/** Lists every flag the script reads, value flags and switches alike. */
+export const FLAGS = [...VALUE_FLAGS, '--codex', '--claude'];
+/** Holds the real Codex commands and the journal and interval the script uses. */
+export const CODEX_FLOW = {
+    status: { command: 'codex', args: ['login', 'status'] },
+    device: { command: 'codex', args: ['login', '--device-auth'] },
+    journal: JOURNAL,
+    intervalMs: POLL_MS,
+};
+/** Holds the real Claude status command. */
+export const CLAUDE_STATUS = { command: 'claude', args: ['auth', 'status'] };
+/**
+ * Reads the value that follows a flag.
+ *
+ * @remarks
+ * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
+ * and the `--flag=value` form is not read.
+ *
+ * @param argv - The arguments after the script path.
+ * @param name - The flag, such as `--cap`.
+ * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
+ * another flag.
+ */
+export function readOption(argv, name) {
+    const index = argv.indexOf(name);
+    const value = index === -1 ? undefined : argv[index + 1];
+    return value === undefined || value.startsWith('--') ? undefined : value;
 }
-function killTree(pid) {
+/**
+ * Names the value flags a caller gave with no value.
+ *
+ * @param argv - The arguments after the script path.
+ * @param names - The flags that take a value.
+ * @returns Each named flag that appears last or is followed by another flag, in argument order.
+ */
+export function readMissingFlags(argv, names) {
+    return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
+}
+/**
+ * Names the flags a caller gave that the script does not read.
+ *
+ * @remarks
+ * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
+ * scan.
+ *
+ * @param argv - The arguments after the script path.
+ * @param flags - Every flag the script reads, value flags and switches alike.
+ * @returns Each argument that opens with `--` and is not a read flag, in argument order.
+ */
+export function readUnknownFlags(argv, flags) {
+    const end = argv.indexOf('--');
+    return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
+}
+/**
+ * Parses the `--cap` value into a number of seconds.
+ *
+ * @param text - The value after `--cap`, or undefined when the flag is absent.
+ * @returns The default cap when the flag is absent, the number when it is finite, above 0, and at
+ * most the longest cap, and undefined otherwise.
+ */
+export function parseCap(text) {
+    if (text === undefined)
+        return DEFAULT_CAP;
+    const cap = Number(text);
+    return Number.isFinite(cap) && cap > 0 && cap <= MAX_CAP_SECONDS ? cap : undefined;
+}
+/**
+ * Runs a status command and reads whether it reports a login.
+ *
+ * @param command - The executable.
+ * @param args - The status arguments.
+ * @param timeoutMs - The milliseconds the command may run before it is ended, above 0; omit it for no
+ * bound.
+ * @returns Live when the command exits 0, with the text it printed, the reason it could not start,
+ * or the note that it did not answer in time.
+ */
+export function readLoginStatus(command, args, timeoutMs) {
+    const result = spawnSync(command, args, {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: timeoutMs,
+    });
+    if (result.error !== undefined) {
+        if ('code' in result.error && result.error.code === 'ETIMEDOUT') {
+            return { started: true, live: false, text: `${command} did not answer within the cap` };
+        }
+        return {
+            started: false,
+            live: false,
+            text: `${command} could not start: ${result.error.message}`,
+        };
+    }
+    return {
+        started: true,
+        live: result.status === 0,
+        text: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim(),
+    };
+}
+/**
+ * Asks a process and the processes it started to end.
+ *
+ * @param pid - The process to end. A process that is already gone is not an error.
+ */
+export function terminateTree(pid) {
     if (process.platform === 'win32') {
         spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
         return;
@@ -30,63 +143,113 @@ function killTree(pid) {
     }
     catch { }
 }
-function waitFor(ms) {
+/**
+ * Waits a number of milliseconds.
+ *
+ * @param ms - The milliseconds to wait.
+ * @returns A promise that resolves when the time has passed.
+ */
+export function waitFor(ms) {
     return new Promise((resolve) => {
         setTimeout(resolve, ms);
     });
 }
-async function pollLogin(started, capSeconds, url, code) {
-    if (Date.now() - started >= capSeconds * 1000)
+/**
+ * Polls the login journal and the login status until the bench is logged in or the cap ends.
+ *
+ * @param started - The time the login began, in milliseconds since the epoch.
+ * @param capSeconds - The seconds the poll may run.
+ * @param flow - The status command, the journal to read, and the milliseconds between polls.
+ * @param announce - Receives each line the poll tells the user, such as the URL to open.
+ * @param url - The verification URL already read, if any.
+ * @param code - The one-time code already read, if any.
+ * @returns The URL, the code, and whether the bench is logged in.
+ */
+export async function pollLogin(started, capSeconds, flow, announce, url, code) {
+    const deadline = started + capSeconds * 1000;
+    if (Date.now() >= deadline)
         return { url, code, live: false };
-    await waitFor(POLL_MS);
-    const text = existsSync(JOURNAL) ? readFileSync(JOURNAL, 'utf8') : '';
+    await waitFor(flow.intervalMs);
+    const text = existsSync(flow.journal) ? readFileSync(flow.journal, 'utf8') : '';
     const nextUrl = url ?? text.match(URL_PATTERN)?.[0];
     if (url === undefined && nextUrl !== undefined)
-        console.error(`login: open ${nextUrl}`);
+        announce(`login: open ${nextUrl}`);
     const nextCode = code ?? text.match(CODE_PATTERN)?.[1];
-    if (code === undefined && nextCode !== undefined) {
-        console.error(`login: enter the code ${nextCode}`);
-    }
-    if (readStatus('codex', ['login', 'status']).live) {
+    if (code === undefined && nextCode !== undefined)
+        announce(`login: enter the code ${nextCode}`);
+    const remaining = Math.max(deadline - Date.now(), STATUS_GRACE_MS);
+    if (readLoginStatus(flow.status.command, flow.status.args, remaining).live) {
         return { url: nextUrl, code: nextCode, live: true };
     }
-    return pollLogin(started, capSeconds, nextUrl, nextCode);
+    return pollLogin(started, capSeconds, flow, announce, nextUrl, nextCode);
 }
-async function loginCodex(capSeconds) {
-    const before = readStatus('codex', ['login', 'status']);
-    if (before.live) {
-        console.log(JSON.stringify({ bench: 'codex', live: true, status: before.text }));
-        return 0;
+/**
+ * Recovers the Codex login with the device-auth flow.
+ *
+ * @param capSeconds - The seconds the poll may run.
+ * @param flow - The status and device-auth commands, the journal, and the poll interval.
+ * @param announce - Receives each line the poll tells the user, such as the URL to open.
+ * @returns Exit 0 when logged in, 3 when not, with the report to print.
+ */
+export async function loginCodex(capSeconds, flow, announce) {
+    const before = readLoginStatus(flow.status.command, flow.status.args, capSeconds * 1000);
+    // A Codex that cannot start cannot log in either, so the device-auth login never spawns.
+    if (before.live || !before.started) {
+        return {
+            report: { bench: 'codex', live: before.live, status: before.text },
+            exit: before.live ? 0 : 3,
+        };
     }
-    mkdirSync('tmp/codex', { recursive: true });
-    const journal = openSync(JOURNAL, 'w');
+    mkdirSync(dirname(flow.journal), { recursive: true });
+    const journal = openSync(flow.journal, 'w');
     const started = Date.now();
-    const child = spawn('codex', ['login', '--device-auth'], {
+    const child = spawn(flow.device.command, flow.device.args, {
         stdio: ['ignore', journal, journal],
         windowsHide: true,
     });
-    const { url, code, live } = await pollLogin(started, capSeconds);
+    const { url, code, live } = await pollLogin(started, capSeconds, flow, announce);
     if (child.exitCode === null && child.pid !== undefined)
-        killTree(child.pid);
+        terminateTree(child.pid);
     closeSync(journal);
-    console.log(JSON.stringify({
-        bench: 'codex',
-        live,
-        url,
-        code,
-        durationMs: Date.now() - started,
-        journal: JOURNAL,
-        status: readStatus('codex', ['login', 'status']).text,
-    }));
-    return live ? 0 : 3;
+    return {
+        report: {
+            bench: 'codex',
+            live,
+            url,
+            code,
+            durationMs: Date.now() - started,
+            journal: flow.journal,
+            status: readLoginStatus(flow.status.command, flow.status.args, STATUS_GRACE_MS).text,
+        },
+        exit: live ? 0 : 3,
+    };
 }
-function loginClaude() {
-    const status = readStatus('claude', ['auth', 'status']);
-    console.log(JSON.stringify({ bench: 'claude', live: status.live, status: status.text }));
-    return status.live ? 0 : 3;
+/**
+ * Reads the Claude login status.
+ *
+ * @param status - The command that reports the Claude login.
+ * @returns Exit 0 when logged in, 3 when not, with the report to print.
+ */
+export function loginClaude(status) {
+    const read = readLoginStatus(status.command, status.args);
+    return {
+        report: { bench: 'claude', live: read.live, status: read.text },
+        exit: read.live ? 0 : 3,
+    };
 }
-async function main(argv) {
-    const missing = readMissingFlags(argv, ['--cap']);
+/**
+ * Runs the script on its arguments.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The exit code: 0 when logged in, 3 when not, 64 on usage.
+ */
+export async function main(argv) {
+    const unknown = readUnknownFlags(argv, FLAGS);
+    if (unknown.length > 0) {
+        console.error(`login: ${unknown.join(', ')} is not a flag this script reads; usage: login.ts --codex [--cap SECONDS] | --claude`);
+        return 64;
+    }
+    const missing = readMissingFlags(argv, VALUE_FLAGS);
     if (missing.length > 0) {
         console.error(`login: ${missing.join(', ')} given with no value`);
         return 64;
@@ -95,13 +258,28 @@ async function main(argv) {
         console.error('usage: login.ts names one bench: --codex [--cap SECONDS] | --claude');
         return 64;
     }
-    if (argv.includes('--codex'))
-        return loginCodex(Number(readOption(argv, '--cap') ?? 600));
-    if (argv.includes('--claude'))
-        return loginClaude();
+    const cap = parseCap(readOption(argv, '--cap'));
+    if (cap === undefined) {
+        console.error(`login: --cap takes a number of seconds above 0 and at most ${String(MAX_CAP_SECONDS)}`);
+        return 64;
+    }
+    if (argv.includes('--codex')) {
+        const outcome = await loginCodex(cap, CODEX_FLOW, (line) => {
+            console.error(line);
+        });
+        console.log(JSON.stringify(outcome.report));
+        return outcome.exit;
+    }
+    if (argv.includes('--claude')) {
+        const outcome = loginClaude(CLAUDE_STATUS);
+        console.log(JSON.stringify(outcome.report));
+        return outcome.exit;
+    }
     console.error('usage: login.ts --codex [--cap SECONDS] | --claude');
     return 64;
 }
-main(process.argv.slice(2)).then((code) => {
-    process.exitCode = code;
-});
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename) {
+    main(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    });
+}