autor3search-typescript 0.1.0

package/dist/cli/cmd-profile.js

@@ -0,0 +1,140 @@
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { loadConfig, parseDuration } from '../config/load.js';
+import { CONFIG_PATH } from '../config/schema.js';
+import { discoverBenchmarks } from '../discover/benchmarks.js';
+import { profileBenchmark } from '../profile/profile.js';
+/** How many hot functions to print per benchmark. */
+const TOP_N = 15;
+/**
+ * Repo-relative directory `.cpuprofile` files are written under. Alongside
+ * `config.yaml`, not in the (baseline-only) state home: `profile` must work
+ * without a baseline ever existing, and the output is meant for a human to
+ * open locally, not for the harness's own cross-run state.
+ */
+const PROFILE_DIRNAME = path.join('.autor3search', 'profiles');
+function fail(message) {
+    process.stderr.write(`error: ${message}\n`);
+    return 2;
+}
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** Declared benchmark ids that are not among the discovered benchmarks. Mirrors cmd-baseline.ts. */
+function missingDeclared(declared, discovered) {
+    const found = new Set(discovered.map((b) => b.id));
+    return declared.filter((id) => !found.has(id));
+}
+function printHotFrames(frames, totalSelfUs) {
+    if (frames.length === 0) {
+        process.stdout.write('    no user-code samples were captured (every sampled frame was Node internals) -- this ' +
+            'benchmark may be too fast to profile meaningfully; try a longer -benchtime.\n');
+        return;
+    }
+    for (const f of frames.slice(0, TOP_N)) {
+        const pct = totalSelfUs > 0 ? (f.selfTimeUs / totalSelfUs) * 100 : 0;
+        const name = f.functionName.length > 0 ? f.functionName : '(anonymous)';
+        process.stdout.write(`    ${pct.toFixed(1).padStart(5)}%  ${name}  ${f.url}:${f.lineNumber}\n`);
+    }
+}
+/**
+ * `profile`: runs the declared benchmarks under Node's built-in `--cpu-prof`
+ * sampling profiler and prints where time actually goes.
+ *
+ * Deliberately does not touch `baseline` or the state home at all: this is
+ * reconnaissance a human runs BEFORE starting the loop, to decide whether
+ * the benchmarks even point at the right code, so it must work with only
+ * `.autor3search/config.yaml` in place.
+ */
+export async function cmdProfile(ctx, argv) {
+    let benchtimeOverride;
+    try {
+        const normalized = argv.map((a) => (/^-[A-Za-z][A-Za-z-]+$/.test(a) ? `-${a}` : a));
+        const { values } = parseArgs({
+            args: normalized,
+            options: { benchtime: { type: 'string' } },
+            strict: true,
+            allowPositionals: false,
+        });
+        benchtimeOverride = values.benchtime;
+    }
+    catch (e) {
+        return fail(messageOf(e));
+    }
+    let config;
+    try {
+        config = await loadConfig(ctx.configPath);
+    }
+    catch (e) {
+        return fail(messageOf(e));
+    }
+    let discovered;
+    try {
+        discovered = await discoverBenchmarks(ctx.repoRoot);
+    }
+    catch (e) {
+        return fail(`could not discover benchmarks: ${messageOf(e)}`);
+    }
+    let benchmarks;
+    const declared = config.benchmarks;
+    if (declared.length > 0) {
+        const missing = missingDeclared(declared, discovered);
+        if (missing.length > 0) {
+            return fail(`config declares benchmark(s) that no longer exist: ${missing.join(', ')}. Update ` +
+                `${CONFIG_PATH} or restore the missing benchmark(s).`);
+        }
+        const byId = new Map(discovered.map((b) => [b.id, b]));
+        benchmarks = declared.map((id) => byId.get(id));
+    }
+    else {
+        benchmarks = discovered;
+    }
+    if (benchmarks.length === 0) {
+        return fail('no benchmarks found: there is nothing to profile');
+    }
+    let benchtimeMs;
+    let warmupMs;
+    let timeoutMs;
+    try {
+        benchtimeMs = parseDuration(benchtimeOverride ?? config.benchtime);
+        warmupMs = parseDuration(config.warmup);
+        timeoutMs = parseDuration(config.timeout);
+    }
+    catch (e) {
+        return fail(messageOf(e));
+    }
+    const profileDir = path.join(ctx.repoRoot, PROFILE_DIRNAME);
+    process.stdout.write('autor3search-typescript profile -- where does the time actually go?\n\n');
+    let failures = 0;
+    for (const b of benchmarks) {
+        process.stdout.write(`${b.id}\n`);
+        try {
+            const result = await profileBenchmark({
+                cwd: ctx.repoRoot,
+                benchFileAbs: path.join(ctx.repoRoot, b.file),
+                fn: b.fn,
+                id: b.id,
+                benchtimeMs,
+                warmupMs,
+                timeoutMs,
+                nodeArgs: config.nodeArgs,
+                profileDir,
+            });
+            printHotFrames(result.hotFrames, result.totalSelfUs);
+            process.stdout.write(`    profile written to ${result.profilePath}\n`);
+            process.stdout.write('    open it in Chrome DevTools (chrome://inspect -> Open dedicated DevTools for Node -> ' +
+                'Profiler tab -> Load) or drag it into https://www.speedscope.app/\n');
+        }
+        catch (e) {
+            failures++;
+            process.stderr.write(`  error: ${messageOf(e)}\n`);
+        }
+        process.stdout.write('\n');
+    }
+    if (failures > 0) {
+        process.stderr.write(`${failures} of ${benchmarks.length} benchmark(s) could not be profiled\n`);
+        return 2;
+    }
+    return 0;
+}
+//# sourceMappingURL=cmd-profile.js.map

package/dist/cli/cmd-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cmd-profile.js","sourceRoot":"","sources":["../../src/cli/cmd-profile.ts"],"names":[],"mappings":"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"}

package/dist/cli/cmd-report.d.ts

@@ -0,0 +1,15 @@
+import type { RunCtx } from './runctx.js';
+/**
+ * `report`: what a human reads in the morning after an unattended run --
+ * a summary of `results.tsv`, and nothing else. Read-only: it never writes
+ * anything, and it never spawns anything (no git, no subprocess), so it is
+ * always safe to run alongside a live loop.
+ *
+ * A missing (or header-only) `results.tsv` is a real, valid state -- a
+ * repository that has never run an experiment -- so it is reported as "no
+ * experiments recorded yet," not as an error. `loadRows` already treats a
+ * missing file as an empty log; this only needs to word the empty case
+ * helpfully instead of printing zeroed-out counts a human could misread as
+ * "something ran and did nothing."
+ */
+export declare function cmdReport(ctx: RunCtx, _argv: readonly string[]): Promise<number>;

package/dist/cli/cmd-report.js

@@ -0,0 +1,70 @@
+import { shortSha } from '../gitx/git.js';
+import { RESULTS_PATH, loadRows, summarize } from '../results/results.js';
+import { formatCumulativeSpeedup } from './speedup.js';
+const STATUSES = ['keep', 'discard', 'fail', 'crash'];
+function fail(message) {
+    process.stderr.write(`error: ${message}\n`);
+    return 2;
+}
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * `report`: what a human reads in the morning after an unattended run --
+ * a summary of `results.tsv`, and nothing else. Read-only: it never writes
+ * anything, and it never spawns anything (no git, no subprocess), so it is
+ * always safe to run alongside a live loop.
+ *
+ * A missing (or header-only) `results.tsv` is a real, valid state -- a
+ * repository that has never run an experiment -- so it is reported as "no
+ * experiments recorded yet," not as an error. `loadRows` already treats a
+ * missing file as an empty log; this only needs to word the empty case
+ * helpfully instead of printing zeroed-out counts a human could misread as
+ * "something ran and did nothing."
+ */
+export async function cmdReport(ctx, _argv) {
+    let rows;
+    try {
+        rows = await loadRows(ctx.resultsPath);
+    }
+    catch (e) {
+        return fail(messageOf(e));
+    }
+    const lines = ['autor3search-typescript report', ''];
+    if (rows.length === 0) {
+        lines.push(`no experiments recorded yet (${RESULTS_PATH} does not exist, or has no rows). Run "eval" ` +
+            'at least once to populate it.');
+        process.stdout.write(`${lines.join('\n')}\n`);
+        return 0;
+    }
+    const summary = summarize(rows);
+    lines.push(`experiments: ${rows.length} total`);
+    lines.push(`  ${STATUSES.map((s) => `${s}: ${summary.counts[s] ?? 0}`).join('  ')}`);
+    lines.push('');
+    // Deliberately spelled out rather than left implicit: each KEEP advances
+    // the measurement baseline to the just-kept commit, so every kept row's
+    // own `score` is only that experiment's incremental contribution on top
+    // of the last win -- never a re-measurement against the run's original
+    // starting point. Only the PRODUCT of every kept score is the true
+    // end-to-end speedup since the run began; printing (or reading) the
+    // latest row's score alone would silently understate or overstate that,
+    // depending on how many wins came before it.
+    lines.push(`cumulative speedup: ${formatCumulativeSpeedup(summary.cumulativeSpeedup)} ` +
+        "(the product of every KEPT experiment's own score, compounded across the whole run -- " +
+        "not the most recent experiment's score by itself)");
+    if (summary.topWins.length > 0) {
+        lines.push('');
+        lines.push('largest individual wins (own score, biggest improvement first):');
+        for (const w of summary.topWins) {
+            const desc = w.description.length > 0 ? ` -- ${w.description}` : '';
+            lines.push(`  ${shortSha(w.commit)}  score=${w.score.toFixed(4)}  best_bench_delta=${w.bestBenchDelta.toFixed(2)}%${desc}`);
+        }
+    }
+    else {
+        lines.push('');
+        lines.push('no kept experiments yet.');
+    }
+    process.stdout.write(`${lines.join('\n')}\n`);
+    return 0;
+}
+//# sourceMappingURL=cmd-report.js.map

package/dist/cli/cmd-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cmd-report.js","sourceRoot":"","sources":["../../src/cli/cmd-report.ts"],"names":[],"mappings":"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"}

package/dist/cli/cmd-status.d.ts

@@ -0,0 +1,11 @@
+import type { RunCtx } from './runctx.js';
+/**
+ * `status`: reports where a run is, without changing it. It reads only the
+ * baseline record, `results.tsv`, the eval lock and the stop file (plus two
+ * read-only `git` queries for the human's own current branch/HEAD) --
+ * nothing here is ever written. `-tag` resolves the run directory from the
+ * repo root and the tag alone (see `state/home.ts`'s `runDir`), independent
+ * of whatever branch the repository happens to be on right now, so a human
+ * who has wandered off the run branch can still check on it.
+ */
+export declare function cmdStatus(ctx: RunCtx, argv: readonly string[]): Promise<number>;

package/dist/cli/cmd-status.js

@@ -0,0 +1,143 @@
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { currentBranch, headCommit, shortSha } from '../gitx/git.js';
+import { loadRows, summarize } from '../results/results.js';
+import { readBaseline } from '../state/baseline.js';
+import { runDir } from '../state/home.js';
+import { readEvalLock } from '../state/lock.js';
+import { BRANCH_PREFIX, WORKTREE_DIRNAME, inferTagFromBranch } from '../state/runnaming.js';
+import { readStop } from '../state/stop.js';
+import { formatCumulativeSpeedup } from './speedup.js';
+const STATUSES = ['keep', 'discard', 'fail', 'crash'];
+function fail(message) {
+    process.stderr.write(`error: ${message}\n`);
+    return 2;
+}
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Mirrors lock.ts's private `isAlive` (not exported): EPERM means the
+ * process exists but we lack permission to signal it, which is still
+ * "alive." `status` only ever uses this to word its report ("running" vs.
+ * "a crashed eval's stale lock") -- it never reclaims anything, which stays
+ * `acquireEvalLock`'s job alone, so a merely-informational check here can
+ * never race a real acquire.
+ */
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+async function tryGit(f) {
+    try {
+        return await f();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `status`: reports where a run is, without changing it. It reads only the
+ * baseline record, `results.tsv`, the eval lock and the stop file (plus two
+ * read-only `git` queries for the human's own current branch/HEAD) --
+ * nothing here is ever written. `-tag` resolves the run directory from the
+ * repo root and the tag alone (see `state/home.ts`'s `runDir`), independent
+ * of whatever branch the repository happens to be on right now, so a human
+ * who has wandered off the run branch can still check on it.
+ */
+export async function cmdStatus(ctx, argv) {
+    let tag;
+    try {
+        const normalized = argv.map((a) => (/^-[A-Za-z][A-Za-z-]+$/.test(a) ? `-${a}` : a));
+        const { values } = parseArgs({
+            args: normalized,
+            options: { tag: { type: 'string' } },
+            strict: true,
+            allowPositionals: false,
+        });
+        tag = values.tag;
+    }
+    catch (e) {
+        return fail(messageOf(e));
+    }
+    let resolvedTag;
+    try {
+        resolvedTag = tag ?? (await inferTagFromBranch(ctx.repoRoot));
+    }
+    catch (e) {
+        return fail(messageOf(e));
+    }
+    const dir = runDir(ctx.repoRoot, resolvedTag);
+    let baseline;
+    try {
+        baseline = await readBaseline(dir);
+    }
+    catch (e) {
+        return fail(messageOf(e));
+    }
+    const [branch, head, lock, stop, rows] = await Promise.all([
+        tryGit(() => currentBranch(ctx.repoRoot)),
+        tryGit(() => headCommit(ctx.repoRoot)),
+        readEvalLock(dir),
+        readStop(dir),
+        loadRows(ctx.resultsPath),
+    ]);
+    const runBranch = `${BRANCH_PREFIX}${resolvedTag}`;
+    const worktreeDir = path.join(dir, WORKTREE_DIRNAME);
+    const worktreePresent = await exists(worktreeDir);
+    const summary = summarize(rows);
+    const lines = [];
+    lines.push(`autor3search-typescript status -- tag ${JSON.stringify(resolvedTag)}`);
+    lines.push(`  run branch:      ${runBranch}`);
+    lines.push(`  current branch:  ${branch ?? 'unknown'}` + (branch === runBranch ? '' : '  (not on the run branch)'));
+    lines.push(`  frozen commit:   ${shortSha(baseline.frozenCommit)} (${baseline.frozenCommit})`);
+    lines.push(`  measure commit:  ${shortSha(baseline.measureCommit)} (${baseline.measureCommit})`);
+    lines.push(`  HEAD:            ${head === null ? 'unknown' : `${shortSha(head)} (${head})`}`);
+    lines.push(`  worktree:        ${worktreeDir} (${worktreePresent ? 'present' : 'MISSING'})`);
+    if (lock === null) {
+        lines.push('  eval:            idle');
+    }
+    else if (isPidAlive(lock.pid)) {
+        lines.push(`  eval:            running (pid ${lock.pid})`);
+    }
+    else {
+        lines.push(`  eval:            not running (stale lock left by pid ${lock.pid} -- a previous eval likely crashed)`);
+    }
+    if (stop === null) {
+        lines.push('  stop:            none pending');
+    }
+    else {
+        const detail = stop.force
+            ? 'the running eval was asked to abandon its current experiment immediately'
+            : 'the agent will stop after its current experiment reports a verdict';
+        lines.push(`  stop:            requested at ${stop.requestedAt} (force: ${stop.force ? 'yes' : 'no'}) -- ${detail}`);
+    }
+    lines.push(`  experiments:     ${rows.length} total`);
+    lines.push(`    ${STATUSES.map((s) => `${s}: ${summary.counts[s] ?? 0}`).join('  ')}`);
+    lines.push(`  cumulative speedup: ${formatCumulativeSpeedup(summary.cumulativeSpeedup)}`);
+    if (summary.topWins.length > 0) {
+        lines.push('  top wins:');
+        for (const w of summary.topWins) {
+            const desc = w.description.length > 0 ? ` -- ${w.description}` : '';
+            lines.push(`    ${shortSha(w.commit)}  score=${w.score.toFixed(4)}${desc}`);
+        }
+    }
+    process.stdout.write(`${lines.join('\n')}\n`);
+    return 0;
+}
+//# sourceMappingURL=cmd-status.js.map

package/dist/cli/cmd-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cmd-status.js","sourceRoot":"","sources":["../../src/cli/cmd-status.ts"],"names":[],"mappings":"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"}

package/dist/cli/cmd-stop.d.ts

@@ -0,0 +1,15 @@
+import type { RunCtx } from './runctx.js';
+/**
+ * `stop`: asks a running (or about-to-run) `eval` loop to end.
+ *
+ * Plain `stop` only ever writes `stop.json` -- the agent reads it at its
+ * next verdict, so the in-flight experiment always finishes and is scored.
+ * `-clear` cancels a pending request. `-force` additionally signals the pid
+ * recorded in `eval.lock` (if any) to abandon the current experiment right
+ * now -- using `runner/exec.ts`'s own exported `killGroup`, so the pid-1
+ * refusal lives in exactly one place -- and then reports the repository
+ * state that leaves -- including the exact command that would drop the
+ * abandoned commit -- WITHOUT running it. Dropping an agent's work is the
+ * human's decision, never this tool's.
+ */
+export declare function cmdStop(ctx: RunCtx, argv: readonly string[]): Promise<number>;

package/dist/cli/cmd-stop.js

@@ -0,0 +1,143 @@
+import { parseArgs } from 'node:util';
+import { currentBranch, headCommit, shortSha } from '../gitx/git.js';
+import { killGroup } from '../runner/exec.js';
+import { readBaseline } from '../state/baseline.js';
+import { runDir } from '../state/home.js';
+import { readEvalLock } from '../state/lock.js';
+import { inferTagFromBranch } from '../state/runnaming.js';
+import { clearStop, requestStop } from '../state/stop.js';
+function fail(message) {
+    process.stderr.write(`error: ${message}\n`);
+    return 2;
+}
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+async function tryGit(f) {
+    try {
+        return await f();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Mirrors lock.ts's private `isAlive` (not exported): EPERM means the
+ * process exists but we lack permission to signal it, which is still
+ * "alive." Used here only to word the report honestly -- a lock recording a
+ * pid that already died (the eval crashed, or a previous `-force` already
+ * killed it) must not be reported as "signalled" just because the file is
+ * still there; `readEvalLock` itself never checks this (see its own doc
+ * comment), so a caller that needs to know still has to.
+ */
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * `stop`: asks a running (or about-to-run) `eval` loop to end.
+ *
+ * Plain `stop` only ever writes `stop.json` -- the agent reads it at its
+ * next verdict, so the in-flight experiment always finishes and is scored.
+ * `-clear` cancels a pending request. `-force` additionally signals the pid
+ * recorded in `eval.lock` (if any) to abandon the current experiment right
+ * now -- using `runner/exec.ts`'s own exported `killGroup`, so the pid-1
+ * refusal lives in exactly one place -- and then reports the repository
+ * state that leaves -- including the exact command that would drop the
+ * abandoned commit -- WITHOUT running it. Dropping an agent's work is the
+ * human's decision, never this tool's.
+ */
+export async function cmdStop(ctx, argv) {
+    let tag;
+    let clear;
+    let force;
+    try {
+        const normalized = argv.map((a) => (/^-[A-Za-z][A-Za-z-]+$/.test(a) ? `-${a}` : a));
+        const { values } = parseArgs({
+            args: normalized,
+            options: {
+                tag: { type: 'string' },
+                clear: { type: 'boolean', default: false },
+                force: { type: 'boolean', default: false },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+        tag = values.tag;
+        clear = values.clear === true;
+        force = values.force === true;
+    }
+    catch (e) {
+        return fail(messageOf(e));
+    }
+    if (clear && force) {
+        return fail('-clear and -force are mutually exclusive');
+    }
+    let resolvedTag;
+    try {
+        resolvedTag = tag ?? (await inferTagFromBranch(ctx.repoRoot));
+    }
+    catch (e) {
+        return fail(messageOf(e));
+    }
+    const dir = runDir(ctx.repoRoot, resolvedTag);
+    try {
+        // Confirms a run actually exists before writing (or clearing) any state
+        // for it. A human who mistypes a tag must be told the tag is unknown,
+        // not silently handed a stop request that nothing will ever read.
+        // readBaseline never creates anything -- only reads -- so a nonexistent
+        // run is refused here before any state is touched.
+        await readBaseline(dir);
+    }
+    catch (e) {
+        return fail(messageOf(e));
+    }
+    if (clear) {
+        await clearStop(dir);
+        process.stdout.write(`stop request for tag ${JSON.stringify(resolvedTag)} cleared\n`);
+        return 0;
+    }
+    await requestStop(dir, force);
+    if (!force) {
+        process.stdout.write(`stop requested for tag ${JSON.stringify(resolvedTag)}: the agent will stop after its current ` +
+            'experiment reports a verdict.\n');
+        return 0;
+    }
+    process.stdout.write(`stop -force requested for tag ${JSON.stringify(resolvedTag)}.\n`);
+    const lock = await readEvalLock(dir);
+    const signalled = lock !== null && isPidAlive(lock.pid);
+    if (lock === null) {
+        process.stdout.write('  no eval lock is currently held: nothing to signal.\n');
+    }
+    else if (!signalled) {
+        process.stdout.write(`  eval.lock names pid ${lock.pid}, but it is no longer running (a previous eval likely ` +
+            'crashed, or was already stopped): nothing to signal.\n');
+    }
+    else {
+        killGroup(lock.pid, 'SIGTERM');
+        process.stdout.write(`  signalled pid ${lock.pid} (SIGTERM) to abandon its current experiment.\n`);
+    }
+    const branch = await tryGit(() => currentBranch(ctx.repoRoot));
+    const head = await tryGit(() => headCommit(ctx.repoRoot));
+    process.stdout.write(`  current branch: ${branch ?? 'unknown'}\n`);
+    process.stdout.write(`  HEAD commit:    ${head === null ? 'unknown' : `${shortSha(head)} (${head})`}\n`);
+    // Only claim a commit was actually abandoned when something was really
+    // signalled -- with no eval lock held, HEAD is just whatever the last
+    // completed experiment left behind, not something this invocation
+    // interrupted. Either way, nothing has been changed here; dropping a
+    // commit is the human's call, never this tool's, so the reset command is
+    // only ever printed, never run.
+    process.stdout.write(signalled
+        ? '  this is very likely the commit for the experiment just abandoned. Nothing here has been\n' +
+            '  changed -- dropping it is your call, not this tool\'s. To drop it:\n'
+        : '  no eval was running, so nothing was abandoned. If HEAD above is still an unwanted\n' +
+            '  experiment, nothing here has been changed -- dropping it is your call. To drop it:\n');
+    process.stdout.write('\n    git reset --hard HEAD~1\n');
+    return 0;
+}
+//# sourceMappingURL=cmd-stop.js.map

package/dist/cli/cmd-stop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cmd-stop.js","sourceRoot":"","sources":["../../src/cli/cmd-stop.ts"],"names":[],"mappings":"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"}

package/dist/cli/main.d.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { type RunCtx } from './runctx.js';
+type Command = (ctx: RunCtx, argv: string[]) => Promise<number>;
+/**
+ * The command table.
+ *
+ * Ruling 34: a command implemented and tested but never added here is
+ * unreachable, yet looks completely healthy from inside its own task's
+ * suite -- the missing piece lives in a file that task never touches, and
+ * `--help` would still print successfully, just without it. Every command
+ * task must register itself here, and prove it with a test that dispatches
+ * through `main`, not one that only calls the command function directly.
+ * Exported (only) so the COMMANDS/HELP invariant test below can compare
+ * this table's keys against what `--help` actually lists.
+ */
+export declare const COMMANDS: Record<string, Command>;
+/**
+ * Dispatch only: parse the leading `-C <dir>`, take the subcommand, and
+ * delegate. Every command is `(ctx, argv) => Promise<number>`, and its
+ * return value becomes the process exit code directly -- exit codes are
+ * reserved project-wide (0 KEEP, 1 DISCARD, 2 FAIL, 3 CRASH), and a usage
+ * error or an `init` failure is a FAIL (2).
+ *
+ * This function never rejects: everything below -- including `resolveCtx`
+ * failing on a `-C` outside any git repository -- is caught here and
+ * turned into `error: <message>` on stderr plus a `2` return, never a raw
+ * stack trace. That makes it directly testable (call it, read the
+ * returned number) without a test having to unwrap a promise rejection.
+ */
+export declare function main(argv: string[]): Promise<number>;
+export {};