@atmin.ai/review 0.1.0-alpha.2

package/dist/cost-report.d.ts

@@ -0,0 +1,40 @@
+export declare function costReport(directory: string): {
+    repository: string;
+    pr: number;
+    headSha: string;
+    baseSha: string;
+    model: "gpt-5.4-2026-03-05" | "cohere/north-mini-code:free" | "deepseek/deepseek-v3.2";
+    rateCard: {
+        inputPerMillionUsd: number;
+        cachedInputPerMillionUsd: number;
+        outputPerMillionUsd: number;
+        checkedAt: string;
+        source: string;
+        providerRoute?: string;
+    };
+    profile: import("./investigation.js").Profile;
+    engineVersion: "r02-10";
+    promptHash: string;
+    toolHash: string;
+    status: "not-started" | "partial" | "completed";
+    stopReason: string | null;
+    finished: boolean;
+    changedFiles: number;
+    addedLines: number;
+    deletedLines: number;
+    binaryFiles: number;
+    inspectedFiles: number;
+    sourceReads: number;
+    modelCalls: number;
+    toolCalls: number;
+    actualInputTokens: number;
+    actualOutputTokens: number;
+    knownCostUsd: number;
+    unsettledCalls: number;
+    unsettledReservedUsd: number;
+    totalCostUsd: number | null;
+    elapsedMs: number | null;
+    findings: number;
+    complexity: string;
+    limits: string;
+};

package/dist/cost-report.js

@@ -0,0 +1,42 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { git, loadReview } from './snapshot.js';
+import { parseProfile } from './investigation.js';
+// Read-only export: include failed/partial runs and unsettled reservations so
+// cheap failures cannot masquerade as low-cost completed reviews.
+export function costReport(directory) {
+    const { packet, result } = loadReview(directory);
+    const receipt = JSON.parse(readFileSync(join(directory, 'receipt.json'), 'utf8'));
+    parseProfile(receipt.profile);
+    const number = (n) => { if (!Number.isFinite(n) || n < 0)
+        throw new Error('Invalid receipt quantity'); return n; };
+    const sum = (field) => receipt.calls.reduce((total, call) => total + number(call[field] ?? 0), 0);
+    const unknown = receipt.calls.filter(c => c.meteredUsd === null);
+    const stat = git(join(directory, 'source.git'), ['diff', '--no-renames', '--no-ext-diff', '--no-textconv', '--numstat', '-z', packet.mergeBaseSha, packet.headSha, '--']).toString('utf8');
+    let addedLines = 0, deletedLines = 0, binaryFiles = 0;
+    for (const entry of stat.split('\0').filter(Boolean)) {
+        const [added, deleted] = entry.split('\t');
+        if (added === '-' || deleted === '-')
+            binaryFiles++;
+        else {
+            addedLines += number(Number(added));
+            deletedLines += number(Number(deleted));
+        }
+    }
+    const source = result.evidence.filter(e => e.provenance === 'controller-captured');
+    return { repository: packet.repository, pr: packet.pr, headSha: packet.headSha, baseSha: packet.baseSha,
+        model: receipt.profile.model, rateCard: receipt.rateCard, profile: receipt.profile,
+        engineVersion: receipt.engineVersion, promptHash: receipt.promptHash, toolHash: receipt.toolHash,
+        status: result.status, stopReason: receipt.stopReason, finished: receipt.stopReason === 'finished' && result.status === 'completed',
+        changedFiles: packet.changedFiles.length, addedLines, deletedLines, binaryFiles,
+        inspectedFiles: new Set(source.flatMap(e => e.anchors.map(a => a.path))).size,
+        sourceReads: source.length, modelCalls: receipt.calls.length, toolCalls: receipt.toolCalls,
+        // Pending input quantities are estimates, not billed input usage.
+        actualInputTokens: receipt.calls.filter(c => c.outputTokens !== null).reduce((n, c) => n + number(c.inputTokens), 0),
+        actualOutputTokens: sum('outputTokens'), knownCostUsd: sum('meteredUsd'),
+        unsettledCalls: unknown.length, unsettledReservedUsd: unknown.reduce((n, c) => n + number(c.reservedUsd), 0),
+        totalCostUsd: unknown.length ? null : sum('meteredUsd'),
+        elapsedMs: receipt.finishedAt ? number(Date.parse(receipt.finishedAt) - Date.parse(receipt.startedAt)) : null,
+        findings: result.findings.length, complexity: 'unlabelled',
+        limits: 'Source-only inference cost. Code size and inspection breadth are proxies, not measured complexity. Compute, funding fees and human grading are excluded.' };
+}

package/dist/github/api.d.ts

@@ -0,0 +1,66 @@
+import type { ValidationCheck } from '../assessment.js';
+import type { PilotConfig } from './config.js';
+import type { PullState } from '../snapshot.js';
+export interface LivePull extends PullState {
+    draft: boolean;
+}
+export interface Comment {
+    id: number;
+    body: string;
+    user: {
+        login: string;
+        type: string;
+    };
+}
+export interface CheckOutput {
+    status: 'in_progress' | 'completed';
+    conclusion?: 'success' | 'failure' | 'cancelled';
+    output: {
+        title: string;
+        summary: string;
+    };
+    details_url?: string;
+}
+export interface GitHub {
+    pull(pr: number): Promise<LivePull>;
+    canReview(login: string): Promise<boolean>;
+    readToken(): Promise<string>;
+    validation(head: string, names: string[]): Promise<ValidationCheck[]>;
+    summary(pr: number, marker: string): Promise<Comment | null>;
+    create(pr: number, body: string): Promise<number>;
+    update(id: number, body: string): Promise<void>;
+    findCheck(head: string, externalId: string): Promise<number | null>;
+    createCheck(head: string, externalId: string, output: CheckOutput): Promise<number>;
+    updateCheck(id: number, output: CheckOutput): Promise<void>;
+}
+export declare class GitHubError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+export declare function appJwt(appId: string, key: string, now?: number): string;
+export declare class AppGitHub implements GitHub {
+    private config;
+    private appId;
+    private key;
+    private transport;
+    private tokens;
+    private login;
+    constructor(config: PilotConfig, appId: string, key: string, transport?: typeof fetch);
+    private request;
+    private token;
+    readToken(): Promise<string>;
+    verifyInstallation(): Promise<{
+        repository: string;
+        bot: string;
+    }>;
+    pull(pr: number): Promise<LivePull>;
+    canReview(login: string): Promise<boolean>;
+    private botLogin;
+    summary(pr: number, marker: string): Promise<Comment | null>;
+    create(pr: number, body: string): Promise<number>;
+    update(id: number, body: string): Promise<void>;
+    validation(head: string, names: string[]): Promise<ValidationCheck[]>;
+    findCheck(head: string, externalId: string): Promise<number | null>;
+    createCheck(head: string, externalId: string, output: CheckOutput): Promise<number>;
+    updateCheck(id: number, output: CheckOutput): Promise<void>;
+}

package/dist/github/api.js

@@ -0,0 +1,190 @@
+import { sign } from 'node:crypto';
+export class GitHubError extends Error {
+    status;
+    constructor(status) {
+        super(`GitHub request failed (${status})`);
+        this.status = status;
+    }
+}
+export function appJwt(appId, key, now = Date.now()) {
+    const encode = (value) => Buffer.from(JSON.stringify(value)).toString('base64url');
+    const payload = `${encode({ alg: 'RS256', typ: 'JWT' })}.${encode({ iat: Math.floor(now / 1000) - 60, exp: Math.floor(now / 1000) + 540, iss: appId })}`;
+    return `${payload}.${sign('RSA-SHA256', Buffer.from(payload), key).toString('base64url')}`;
+}
+export class AppGitHub {
+    config;
+    appId;
+    key;
+    transport;
+    tokens = new Map();
+    login;
+    constructor(config, appId, key, transport = fetch) {
+        this.config = config;
+        this.appId = appId;
+        this.key = key;
+        this.transport = transport;
+    }
+    async request(path, token, method = 'GET', body) {
+        const response = await this.transport(`https://api.github.com${path}`, {
+            method, redirect: 'error', signal: AbortSignal.timeout(8000),
+            headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2026-03-10', 'User-Agent': 'atmin-review-pilot', ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        }).catch(() => { throw new GitHubError(0); });
+        if (!response.ok)
+            throw new GitHubError(response.status);
+        // API response bodies/errors never enter logs, especially access-token responses.
+        try {
+            return await response.json();
+        }
+        catch {
+            throw new GitHubError(0);
+        }
+    }
+    async token(write) {
+        const scope = write === 'checks' ? 'checks' : write ? 'write' : 'read';
+        const cached = this.tokens.get(scope);
+        if (cached && cached.expires > Date.now() + 120_000)
+            return cached.token;
+        const result = await this.request(`/app/installations/${this.config.installationId}/access_tokens`, appJwt(this.appId, this.key), 'POST', {
+            repository_ids: [this.config.repositoryId],
+            permissions: write === 'checks' ? { checks: 'write' } : write ? { pull_requests: 'write' } : { contents: 'read', pull_requests: 'read' },
+        });
+        if (typeof result.token !== 'string' || !result.token || !Number.isFinite(Date.parse(result.expires_at)))
+            throw new Error('Invalid installation token response');
+        this.tokens.set(scope, { token: result.token, expires: Date.parse(result.expires_at) });
+        return result.token;
+    }
+    readToken() { return this.token(false); }
+    async verifyInstallation() {
+        const data = await this.request(`/repos/${this.config.repository}`, await this.token(false));
+        if (data.id !== this.config.repositoryId || data.full_name !== this.config.repository)
+            throw new Error('Installation repository identity mismatch');
+        // Minting the narrower publisher token checks granted permission without posting anything.
+        await this.token(true);
+        await this.token('checks');
+        return { repository: data.full_name, bot: await this.botLogin() };
+    }
+    async pull(pr) {
+        const token = await this.token(false);
+        const data = await this.request(`/repos/${this.config.repository}/pulls/${pr}`, token);
+        if (data.base?.repo?.id !== this.config.repositoryId || data.base?.repo?.full_name !== this.config.repository || data.number !== pr)
+            throw new Error('PR repository identity mismatch');
+        const ref = await this.request(`/repos/${this.config.repository}/git/ref/heads/${encodeURIComponent(data.base.ref)}`, token);
+        if (![data.head?.sha, ref.object?.sha].every(sha => typeof sha === 'string' && /^[a-f0-9]{40}$/.test(sha)) || typeof data.base.ref !== 'string' || !['open', 'closed'].includes(data.state) || typeof data.draft !== 'boolean')
+            throw new Error('Invalid live PR state');
+        return { repository: this.config.repository, pr, headSha: data.head.sha, baseSha: ref.object.sha, baseRef: data.base.ref, state: data.state, draft: data.draft };
+    }
+    async canReview(login) {
+        if (!/^[a-z\d](?:[a-z\d-]{0,38})$/i.test(login))
+            return false;
+        try {
+            const data = await this.request(`/repos/${this.config.repository}/collaborators/${encodeURIComponent(login)}/permission`, await this.token(false));
+            return ['write', 'maintain', 'admin'].includes(data.permission);
+        }
+        catch (error) {
+            if (error instanceof GitHubError && error.status === 404)
+                return false;
+            throw error;
+        }
+    }
+    async botLogin() {
+        if (!this.login) {
+            const app = await this.request('/app', appJwt(this.appId, this.key));
+            if (typeof app.slug !== 'string' || !/^[a-z\d-]+$/.test(app.slug))
+                throw new Error('Invalid App identity');
+            this.login = `${app.slug}[bot]`;
+        }
+        return this.login;
+    }
+    async summary(pr, marker) {
+        const login = await this.botLogin();
+        const token = await this.token(false);
+        let found = null;
+        for (let page = 1; page <= 20; page++) {
+            const comments = await this.request(`/repos/${this.config.repository}/issues/${pr}/comments?per_page=100&page=${page}`, token);
+            if (!Array.isArray(comments))
+                throw new Error('Invalid comment listing');
+            for (const comment of comments) {
+                if (comment.user?.login === login && comment.user?.type === 'Bot' && typeof comment.body === 'string' && comment.body.startsWith(`${marker}\n`)) {
+                    if (found || !Number.isSafeInteger(comment.id))
+                        throw new Error('Ambiguous bot summary; operator reconciliation required');
+                    found = comment;
+                }
+            }
+            if (comments.length < 100)
+                return found;
+        }
+        throw new Error('Comment scan limit reached; no new comment created');
+    }
+    async create(pr, body) {
+        const result = await this.request(`/repos/${this.config.repository}/issues/${pr}/comments`, await this.token(true), 'POST', { body });
+        if (!Number.isSafeInteger(result.id))
+            throw new Error('Uncertain comment creation');
+        return result.id;
+    }
+    async update(id, body) {
+        await this.request(`/repos/${this.config.repository}/issues/comments/${id}`, await this.token(true), 'PATCH', { body });
+    }
+    async validation(head, names) {
+        if (!/^[a-f0-9]{40}$/.test(head))
+            throw new Error('Invalid CI commit');
+        const checks = [];
+        for (const trusted of this.config.trustedChecks ?? []) {
+            if (!names.includes(trusted.name))
+                continue;
+            const missing = { name: trusted.name, status: 'not-run', reason: 'No unique completed check from the trusted GitHub App on this exact head.' };
+            // The review App cannot attest its own required validation.
+            if (String(trusted.appId) === this.appId) {
+                checks.push(missing);
+                continue;
+            }
+            try {
+                const query = new URLSearchParams({ check_name: trusted.name, app_id: String(trusted.appId), filter: 'latest', per_page: '100' });
+                const data = await this.request(`/repos/${this.config.repository}/commits/${head}/check-runs?${query}`, await this.token('checks'));
+                if (!Array.isArray(data.check_runs) || data.total_count !== data.check_runs.length || data.check_runs.length !== 1) {
+                    checks.push(missing);
+                    continue;
+                }
+                const run = data.check_runs[0];
+                if (run.name !== trusted.name || run.app?.id !== trusted.appId || run.head_sha !== head
+                    || !Number.isSafeInteger(run.id) || run.id < 1 || run.status !== 'completed') {
+                    checks.push(missing);
+                    continue;
+                }
+                const status = run.conclusion === 'success' ? 'pass'
+                    : ['failure', 'timed_out', 'action_required', 'startup_failure'].includes(run.conclusion) ? 'fail' : 'not-run';
+                checks.push({ name: trusted.name, status, reason: `GitHub App ${trusted.appId}, check ${run.id}: ${status === 'pass' ? 'passed' : status === 'fail' ? 'failed' : 'did not establish a pass'}.`,
+                    url: `https://github.com/${this.config.repository}/runs/${run.id}` });
+            }
+            catch {
+                checks.push({ ...missing, reason: 'GitHub CI evidence could not be retrieved. Validation remains unverified.' });
+            }
+        }
+        return checks;
+    }
+    async findCheck(head, externalId) {
+        const token = await this.token('checks');
+        for (let page = 1; page <= 20; page++) {
+            const data = await this.request(`/repos/${this.config.repository}/commits/${head}/check-runs?check_name=atmin%20review&filter=all&per_page=100&page=${page}`, token);
+            if (!Array.isArray(data.check_runs))
+                throw new Error('Invalid check listing');
+            const found = data.check_runs.filter((r) => String(r.app?.id) === this.appId && r.external_id === externalId && r.head_sha === head);
+            if (found.length > 1)
+                throw new Error('Ambiguous check creation');
+            if (found.length === 1 && Number.isSafeInteger(found[0].id))
+                return found[0].id;
+            if (data.check_runs.length < 100)
+                return null;
+        }
+        throw new Error('Check scan limit reached');
+    }
+    async createCheck(head, externalId, output) {
+        const data = await this.request(`/repos/${this.config.repository}/check-runs`, await this.token('checks'), 'POST', { name: 'atmin review', head_sha: head, external_id: externalId, ...output });
+        if (!Number.isSafeInteger(data.id))
+            throw new Error('Uncertain check creation');
+        return data.id;
+    }
+    async updateCheck(id, output) {
+        await this.request(`/repos/${this.config.repository}/check-runs/${id}`, await this.token('checks'), 'PATCH', output);
+    }
+}

package/dist/github/checks.d.ts

@@ -0,0 +1,11 @@
+import type { Assessment } from '../assessment.js';
+import type { GitHub, CheckOutput } from './api.js';
+import type { Job, Store } from './store.js';
+export declare function assessmentCheck(assessment: Assessment): CheckOutput;
+export declare class Checks {
+    private store;
+    private github;
+    constructor(store: Store, github: GitHub);
+    publish(job: Job, head: string, output: CheckOutput): Promise<void>;
+    stop(job: Job, conclusion: 'failure' | 'cancelled', title: string): Promise<void>;
+}

package/dist/github/checks.js

@@ -0,0 +1,42 @@
+export function assessmentCheck(assessment) {
+    const success = assessment.freshness.status === 'current' && assessment.scope === 'complete'
+        && ['passed', 'not-applicable'].includes(assessment.validation) && assessment.findingsVerdict !== 'Changes needed';
+    return { status: 'completed', conclusion: success ? 'success' : 'failure', output: {
+            title: assessment.outcome, summary: `Scope: ${assessment.scope}. Required validation: ${assessment.validation}.\n\n${assessment.reasons.join('\n')}\n\nP0–P2 block this check; P3 and optional P4 do not. This is a review result, not merge approval.`,
+        } };
+}
+// A creation attempt is durable before POST. On a lost response, reconcile by
+// App identity + immutable head + job ID; never blindly create another check.
+export class Checks {
+    store;
+    github;
+    constructor(store, github) {
+        this.store = store;
+        this.github = github;
+        store.db.exec('CREATE TABLE IF NOT EXISTS review_checks (job TEXT PRIMARY KEY, head TEXT NOT NULL, id INTEGER)');
+    }
+    async publish(job, head, output) {
+        let row = this.store.db.prepare('SELECT head,id FROM review_checks WHERE job=?').get(job.id);
+        if (row && row.head !== head)
+            throw new Error('Check snapshot mismatch');
+        let id = row?.id;
+        if (id == null) {
+            id = await this.github.findCheck(head, job.id);
+            if (id == null) {
+                if (row)
+                    throw new Error('Check creation uncertain; reconcile explicitly');
+                this.store.db.prepare('INSERT INTO review_checks(job,head) VALUES(?,?)').run(job.id, head);
+                id = await this.github.createCheck(head, job.id, output);
+                this.store.db.prepare('UPDATE review_checks SET id=? WHERE job=?').run(id, job.id);
+                return;
+            }
+            this.store.db.prepare('INSERT INTO review_checks(job,head,id) VALUES(?,?,?) ON CONFLICT(job) DO UPDATE SET id=excluded.id').run(job.id, head, id);
+        }
+        await this.github.updateCheck(id, output);
+    }
+    async stop(job, conclusion, title) {
+        const row = this.store.db.prepare('SELECT head FROM review_checks WHERE job=?').get(job.id);
+        if (row)
+            await this.publish(job, String(row.head), { status: 'completed', conclusion, output: { title, summary: 'No current completed review is claimed. See the PR summary and operator status.' } });
+    }
+}

package/dist/github/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/github/cli.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { readConfig, requiredEnv } from './config.js';
+import { Store } from './store.js';
+import { AppGitHub } from './api.js';
+import { webhook } from './webhook.js';
+import { Worker } from './worker.js';
+import { engineRunner } from './runner.js';
+import { readProfile } from '../run.js';
+async function main() {
+    const [operation, input, prInput] = process.argv.slice(2);
+    if (!operation || operation === '--help') {
+        process.stdout.write(`atmin review GitHub pilot\n\n  atmin-review-github serve|check <config.json>\n  atmin-review-github status|enable|pause <config.json>\n  atmin-review-github enqueue|reconcile <config.json> <pr-number>\n\nStarts paused. Operator controls are local only. Requires Node 24+, git and gh.\n`);
+        return;
+    }
+    if (!input || !['serve', 'check', 'status', 'enable', 'pause', 'enqueue', 'reconcile'].includes(operation))
+        throw new Error('Invalid pilot command; use --help');
+    const config = readConfig(resolve(input));
+    process.umask(0o077);
+    if (operation === 'check') {
+        requiredEnv(readProfile(config.profile).provider === 'openrouter' ? 'OPENROUTER_API_KEY' : 'OPENAI_API_KEY');
+        if (Buffer.byteLength(requiredEnv('GITHUB_WEBHOOK_SECRET')) < 32)
+            throw new Error('Use a webhook secret of at least 32 bytes');
+        const github = new AppGitHub(config, requiredEnv('GITHUB_APP_ID'), readFileSync(requiredEnv('GITHUB_APP_PRIVATE_KEY_PATH'), 'utf8'));
+        process.stdout.write(`${JSON.stringify(await github.verifyInstallation())}\n`);
+        return;
+    }
+    const store = new Store(config.stateDirectory);
+    if (operation !== 'serve') {
+        try {
+            if (operation === 'enable')
+                store.enable(true);
+            if (operation === 'pause')
+                store.enable(false);
+            if (operation === 'enqueue' || operation === 'reconcile') {
+                const pr = Number(prInput);
+                if (!Number.isSafeInteger(pr) || pr < 1)
+                    throw new Error('Expected a positive PR number');
+                if (!store.enabled())
+                    throw new Error('Pilot is paused; enable it first');
+                if (operation === 'enqueue' && !store.enqueue(`operator-${randomUUID()}`, pr))
+                    throw new Error('Review was not queued');
+                if (operation === 'reconcile' && !store.retryPublication(pr))
+                    throw new Error('No current saved report to reconcile');
+            }
+            process.stdout.write(`${JSON.stringify(store.status(), null, 2)}\n`);
+        }
+        finally {
+            store.close();
+        }
+        return;
+    }
+    const secret = requiredEnv('GITHUB_WEBHOOK_SECRET');
+    if (Buffer.byteLength(secret) < 32)
+        throw new Error('Use a webhook secret of at least 32 bytes');
+    const github = new AppGitHub(config, requiredEnv('GITHUB_APP_ID'), readFileSync(requiredEnv('GITHUB_APP_PRIVATE_KEY_PATH'), 'utf8'));
+    const owner = randomUUID();
+    if (!store.acquire(owner))
+        throw new Error('A pilot service already owns this state directory');
+    const server = webhook(config, secret, store, github);
+    const worker = new Worker(config, store, github, engineRunner(config, github), owner);
+    let stopping = false;
+    const stop = () => { stopping = true; worker.stop(); server.close(); };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    const heartbeat = setInterval(() => { if (!store.renew(owner))
+        stop(); }, 5000);
+    try {
+        await new Promise((done, reject) => { server.once('error', reject); server.listen(config.port, config.host, done); });
+        process.stdout.write(`${JSON.stringify({ service: 'atmin review', repository: config.repository, enabled: store.enabled(), host: config.host, port: config.port })}\n`);
+        while (!stopping) {
+            const worked = await worker.tick();
+            if (!worked && !stopping)
+                await new Promise(done => setTimeout(done, 500));
+        }
+    }
+    finally {
+        clearInterval(heartbeat);
+        stop();
+        process.off('SIGINT', stop);
+        process.off('SIGTERM', stop);
+        store.release(owner);
+        store.close();
+    }
+}
+try {
+    await main();
+}
+catch {
+    process.stderr.write('atmin review pilot could not complete the command. Check local configuration, credentials, port and service status.\n');
+    process.exitCode = 1;
+}

package/dist/github/config.d.ts

@@ -0,0 +1,16 @@
+export interface PilotConfig {
+    repository: string;
+    repositoryId: number;
+    installationId: number;
+    profile: string;
+    stateDirectory: string;
+    host: string;
+    port: number;
+    maxReviewsPerDay: number;
+    trustedChecks?: {
+        name: string;
+        appId: number;
+    }[];
+}
+export declare function readConfig(path: string): PilotConfig;
+export declare function requiredEnv(name: string): string;

package/dist/github/config.js

@@ -0,0 +1,41 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { readProfile } from '../run.js';
+export function readConfig(path) {
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    const keys = ['repository', 'repositoryId', 'installationId', 'profile', 'stateDirectory', 'host', 'port', 'maxReviewsPerDay', 'trustedChecks'];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw) || Object.keys(raw).some(k => !keys.includes(k)))
+        throw new Error('Invalid pilot configuration');
+    if (typeof raw.repository !== 'string' || !/^[\w.-]+\/[\w.-]+$/.test(raw.repository))
+        throw new Error('Invalid pilot repository');
+    for (const key of ['repositoryId', 'installationId', 'port', 'maxReviewsPerDay']) {
+        if (!Number.isSafeInteger(raw[key]) || raw[key] < 1)
+            throw new Error(`Set a positive ${key}`);
+    }
+    if (raw.port > 65535 || raw.maxReviewsPerDay > 100)
+        throw new Error('Pilot port or daily review limit out of range');
+    if (!['127.0.0.1', '0.0.0.0', '::1'].includes(raw.host))
+        throw new Error('Unsupported listen address');
+    for (const key of ['profile', 'stateDirectory'])
+        if (typeof raw[key] !== 'string' || !raw[key])
+            throw new Error(`Set ${key}`);
+    if (raw.trustedChecks !== undefined) {
+        if (!Array.isArray(raw.trustedChecks) || raw.trustedChecks.length > 20
+            || raw.trustedChecks.some((c) => !c || typeof c !== 'object' || Array.isArray(c)
+                || Object.keys(c).some(k => !['name', 'appId'].includes(k))
+                || typeof c.name !== 'string' || !c.name.trim() || c.name.length > 200 || c.name === 'atmin review'
+                || !Number.isSafeInteger(c.appId) || c.appId < 1)
+            || new Set(raw.trustedChecks.map((c) => c.name)).size !== raw.trustedChecks.length) {
+            throw new Error('Trusted checks require unique names and positive GitHub App IDs');
+        }
+    }
+    const config = { ...raw, profile: resolve(dirname(path), raw.profile), stateDirectory: resolve(dirname(path), raw.stateDirectory) };
+    readProfile(config.profile);
+    return config;
+}
+export function requiredEnv(name) {
+    const value = process.env[name];
+    if (!value)
+        throw new Error(`Missing ${name}`);
+    return value;
+}

package/dist/github/runner.d.ts

@@ -0,0 +1,7 @@
+import type { PilotConfig } from './config.js';
+import type { GitHub } from './api.js';
+import type { Job } from './store.js';
+export type Runner = (job: Job, signal: AbortSignal) => Promise<string>;
+export declare function childEnvironment(home: string, credentials: Record<string, string>): NodeJS.ProcessEnv;
+export declare function child(args: string[], env: NodeJS.ProcessEnv, signal: AbortSignal, deadlineMs: number): Promise<void>;
+export declare function engineRunner(config: PilotConfig, github: GitHub): Runner;

package/dist/github/runner.js

@@ -0,0 +1,67 @@
+import { spawn } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readProfile } from '../run.js';
+export function childEnvironment(home, credentials) {
+    return { PATH: process.env.PATH ?? '/usr/bin:/bin', HOME: home, TMPDIR: home, GH_CONFIG_DIR: join(home, 'gh'), LANG: 'C.UTF-8', ...credentials };
+}
+export function child(args, env, signal, deadlineMs) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(new Error('cancelled'));
+            return;
+        }
+        const proc = spawn(process.execPath, [fileURLToPath(new URL('./task.js', import.meta.url)), ...args], {
+            env, cwd: env.HOME, stdio: 'ignore', detached: process.platform !== 'win32',
+        });
+        let killTimer;
+        let stopped = false;
+        const kill = (kind) => {
+            try {
+                if (process.platform !== 'win32' && proc.pid)
+                    process.kill(-proc.pid, kind);
+                else
+                    proc.kill(kind);
+            }
+            catch { /* Already exited. */ }
+        };
+        const cancel = () => {
+            if (stopped)
+                return;
+            stopped = true;
+            kill('SIGTERM');
+            killTimer = setTimeout(() => kill('SIGKILL'), 2000);
+        };
+        const deadline = setTimeout(cancel, deadlineMs);
+        signal.addEventListener('abort', cancel, { once: true });
+        const cleanup = () => { clearTimeout(deadline); clearTimeout(killTimer); signal.removeEventListener('abort', cancel); };
+        proc.once('error', () => { cleanup(); reject(new Error('Review child failed to start')); });
+        proc.once('exit', code => { cleanup(); if (code === 0 && !stopped)
+            resolve();
+        else
+            reject(new Error('Review child interrupted or failed')); });
+    });
+}
+export function engineRunner(config, github) {
+    const runs = join(config.stateDirectory, 'runs');
+    mkdirSync(runs, { recursive: true, mode: 0o700 });
+    return async (job, signal) => {
+        const directory = join(runs, job.id);
+        const home = mkdtempSync(join(config.stateDirectory, 'job-home-'));
+        try {
+            const token = await github.readToken();
+            await child(['capture', `https://github.com/${config.repository}/pull/${job.pr}`, directory], childEnvironment(home, { GH_TOKEN: token }), signal, 130_000);
+            const profile = readProfile(config.profile);
+            const keyName = profile.provider === 'openrouter' ? 'OPENROUTER_API_KEY' : 'OPENAI_API_KEY';
+            const key = process.env[keyName];
+            if (!key)
+                throw new Error('Configured model credential unavailable');
+            await child(['investigate', directory, config.profile], childEnvironment(home, { [keyName]: key }), signal, profile.deadlineMs + 30_000);
+            return directory;
+        }
+        finally {
+            rmSync(home, { recursive: true, force: true });
+        }
+    };
+}