@ashulab/carrier 0.0.0-stage → 0.1.1

package/dist/harnesses/host-runner.js

@@ -0,0 +1,225 @@
+import { execFile, spawn } from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { freemem, loadavg } from 'node:os';
+import { promisify } from 'node:util';
+import { failureDetail } from '../execution/failure.js';
+import { createEventState } from '../execution/events.js';
+import { claudeAdapter } from './claude.js';
+import { agyAdapter } from './agy.js';
+import { codexAdapter } from './codex.js';
+import { resolveBinary } from './common.js';
+const exec = promisify(execFile);
+const markerRe = /carrier-exec-([\w-]+)/;
+/** Pids of live processes carrying an execution marker, found in `ps` so another carrier process can see them. */
+async function listMarked() {
+    const { stdout } = await exec('ps', ['-axo', 'pid=,command='], { maxBuffer: 64 * 1024 * 1024 });
+    const found = new Map();
+    for (const line of stdout.split('\n')) {
+        const match = markerRe.exec(line);
+        if (match)
+            found.set(match[1], Number(line.trim().split(/\s+/)[0]));
+    }
+    return found;
+}
+// The agent leads its own process group (detached), so the signal reaches the whole group.
+function signal(pid, sig) {
+    try {
+        process.kill(-pid, sig);
+    }
+    catch {
+        try {
+            process.kill(pid, sig);
+        }
+        catch {
+            // already gone
+        }
+    }
+}
+const spawnError = (message) => ({
+    exit: 'failed',
+    failure: { kind: 'spawn_error', detail: failureDetail(message), exitCode: null, signal: null, hostFreeMemMb: null, hostLoad: null },
+});
+// A failed process: what the exit code and the signal say, and the host at that moment. What the adapter read from the
+// agent's own result names the cause and wins over the symptom; the exit code and the signal are recorded either way.
+function processFailure(code, signal, adapterFailure) {
+    if (adapterFailure)
+        return { kind: adapterFailure.kind, detail: failureDetail(adapterFailure.detail), exitCode: code, signal, hostFreeMemMb: null, hostLoad: null };
+    const kind = signal ? 'killed' : code ? 'crashed' : 'unknown';
+    const detail = signal ?? (code ? `exit code ${code}` : 'the process ended without an exit code');
+    return { kind, detail, exitCode: code, signal, hostFreeMemMb: Math.round(freemem() / 1048576), hostLoad: loadavg()[0] };
+}
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+// SIGTERM first (Claude cleans its children up on it), SIGKILL if it has not exited after the grace period.
+async function terminate(pid, graceMs) {
+    signal(pid, 'SIGTERM');
+    const deadline = Date.now() + graceMs;
+    while (alive(pid) && Date.now() < deadline)
+        await new Promise((r) => setTimeout(r, 50));
+    if (alive(pid))
+        signal(pid, 'SIGKILL');
+}
+export class HostAgentRunner {
+    runs = new Map();
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    run(task) {
+        const sessions = [];
+        const outputs = [];
+        const eventSinks = [];
+        let sessionId;
+        let reason;
+        let pid;
+        const emit = (stream, chunk) => outputs.forEach((cb) => cb(stream, chunk));
+        const graceMs = this.options.graceMs ?? 5000;
+        let finished = false;
+        // Before the spawn there is nothing to kill: start() checks `reason` instead.
+        const kill = async () => {
+            if (pid !== undefined && !finished)
+                await terminate(pid, graceMs);
+        };
+        const start = async () => {
+            const adapter = this.options.adapters?.[task.harness] ?? { claude: claudeAdapter, codex: codexAdapter, agy: agyAdapter }[task.harness];
+            let credentials;
+            try {
+                credentials = await this.options.credentials(task);
+            }
+            catch (e) {
+                // Without a token the run cannot start; retrying does not help, so it is an auth failure, not a technical one.
+                emit('stderr', `carrier: no GitHub token for profile "${task.profile}": ${e instanceof Error ? e.message : String(e)}\n`);
+                return { exit: 'auth_failed' };
+            }
+            if (reason)
+                return { exit: reason };
+            let command;
+            try {
+                const binary = this.options.binaries?.[task.harness] ?? resolveBinary(task.harness);
+                command = adapter.command(task, { binary, baseEnv: process.env, ...credentials });
+                mkdirSync(dirname(task.resultPath), { recursive: true });
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                emit('stderr', `carrier: cannot build the ${task.harness} command: ${message}\n`);
+                return spawnError(`cannot build the ${task.harness} command: ${message}`);
+            }
+            const child = spawn(command.bin, command.args, { cwd: command.cwd, env: command.env, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+            pid = child.pid;
+            let authFailed = false;
+            let sessionLost = false;
+            let adapterFailure;
+            const eventState = createEventState();
+            // The events of the lines of one chunk, to be reported together; only stdout carries the stream.
+            let batch = [];
+            const readLine = (line, stream) => {
+                if (stream === 'stdout')
+                    batch.push(...(adapter.parseEvents?.(line, eventState) ?? []));
+                const signalOfLine = adapter.parseLine(line);
+                if (signalOfLine?.session && !sessionId) {
+                    sessionId = signalOfLine.session;
+                    sessions.forEach((cb) => cb(sessionId));
+                }
+                authFailed ||= signalOfLine?.authFailed === true;
+                sessionLost ||= signalOfLine?.sessionUnavailable === true;
+                adapterFailure ??= signalOfLine?.failure;
+            };
+            const reportEvents = () => {
+                if (batch.length > 0)
+                    eventSinks.forEach((cb) => cb(batch));
+            };
+            // Some errors (Codex's lost session) only show on stderr, so both streams go through the adapter.
+            const lineReader = (stream) => {
+                let pending = '';
+                return {
+                    push: (chunk) => {
+                        emit(stream, chunk);
+                        const lines = (pending + chunk).split('\n');
+                        pending = lines.pop();
+                        batch = [];
+                        lines.forEach((line) => readLine(line, stream));
+                        reportEvents();
+                    },
+                    flush: () => {
+                        if (!pending)
+                            return;
+                        batch = [];
+                        readLine(pending, stream);
+                        reportEvents();
+                    },
+                };
+            };
+            const out = lineReader('stdout');
+            const err = lineReader('stderr');
+            child.stdout.setEncoding('utf8').on('data', out.push);
+            child.stderr.setEncoding('utf8').on('data', err.push);
+            const timer = task.timeoutMs === null ? undefined : setTimeout(() => {
+                reason ??= 'timed_out';
+                void kill();
+            }, task.timeoutMs);
+            let startError;
+            const [code, killedBy] = await new Promise((resolve) => {
+                child.on('error', (e) => {
+                    emit('stderr', `carrier: cannot start ${command.bin}: ${e.message}\n`);
+                    startError = e.message;
+                    resolve([null, null]);
+                });
+                child.on('close', (c, sig) => resolve([c, sig]));
+            });
+            finished = true;
+            clearTimeout(timer);
+            out.flush();
+            err.flush();
+            if (reason)
+                return { exit: reason, sessionId };
+            if (authFailed)
+                return { exit: 'auth_failed', sessionId };
+            if (sessionLost)
+                return { exit: 'session_unavailable', sessionId };
+            if (startError !== undefined)
+                return { ...spawnError(`cannot start ${command.bin}: ${startError}`), sessionId };
+            if (code === 0)
+                return { exit: 'ok', sessionId };
+            return { exit: 'failed', sessionId, failure: processFailure(code, killedBy, adapterFailure) };
+        };
+        const done = start().finally(() => this.runs.delete(task.executionId));
+        const handle = {
+            onSession: (cb) => {
+                sessions.push(cb);
+                if (sessionId)
+                    cb(sessionId);
+            },
+            onOutput: (cb) => void outputs.push(cb),
+            onEvent: (cb) => void eventSinks.push(cb),
+            done,
+            stop: async () => {
+                reason ??= 'stopped';
+                await kill();
+                await done;
+            },
+        };
+        this.runs.set(task.executionId, handle);
+        return handle;
+    }
+    async listActive() {
+        return [...new Set([...this.runs.keys(), ...(await listMarked()).keys()])];
+    }
+    async stop(executionId) {
+        const handle = this.runs.get(executionId);
+        if (handle)
+            return handle.stop();
+        // An orphan from a previous carrier process: no handle, only its pid.
+        const pid = (await listMarked()).get(executionId);
+        if (pid === undefined)
+            return;
+        await terminate(pid, this.options.graceMs ?? 5000);
+    }
+}

package/dist/harnesses/local.js

@@ -0,0 +1,25 @@
+export const localKinds = ['lmstudio', 'ollama'];
+export const localLabel = { lmstudio: 'LM Studio', ollama: 'Ollama' };
+// ponytail: default ports only; a server on another port needs a base-URL setting when someone runs one.
+export const localUrl = { lmstudio: 'http://localhost:1234', ollama: 'http://localhost:11434' };
+/** The environment that points the Claude CLI at a local server, which speaks the Anthropic API on its root URL. */
+export const claudeLocalEnv = (local) => ({
+    ANTHROPIC_BASE_URL: localUrl[local],
+    ANTHROPIC_AUTH_TOKEN: local, // any non-empty value: the local server does not check it
+    ANTHROPIC_API_KEY: '', // a real key in the user's environment must not be sent to a local server
+});
+/** The chat models the server has. Throws when it does not answer, which is how callers tell "not running". */
+export async function listLocalModels(local, fetchJson = defaultFetch) {
+    if (local === 'ollama') {
+        const body = (await fetchJson(`${localUrl.ollama}/api/tags`));
+        return (body.models ?? []).flatMap((m) => (m.name ? [m.name] : []));
+    }
+    const body = (await fetchJson(`${localUrl.lmstudio}/v1/models`));
+    return (body.data ?? []).flatMap((m) => (m.id && !/embed/i.test(m.id) ? [m.id] : [])); // LM Studio lists embedding models too
+}
+async function defaultFetch(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(2000) });
+    if (!response.ok)
+        throw new Error(`${url} answered HTTP ${response.status}`);
+    return response.json();
+}

package/dist/harnesses/names.js

@@ -0,0 +1,9 @@
+/** The agent CLIs Carrier can run; each is also the name of its binary. */
+export const harnessNames = ['claude', 'codex', 'agy'];
+/** The environment variable that points each CLI at its config folder (what an option's `configDir` sets). Antigravity has none. */
+export const configDirVariable = { claude: 'CLAUDE_CONFIG_DIR', codex: 'CODEX_HOME' };
+export const harnessLabel = { claude: 'Claude Code', codex: 'Codex', agy: 'Antigravity' };
+/** Who serves the model when the config names no provider. */
+export const nativeProvider = { claude: 'Anthropic', codex: 'OpenAI', agy: 'Antigravity' };
+/** The local servers a harness can be pointed at. Antigravity has no setting for it (docs/research/antigravity.md). */
+export const localProvidersOf = { claude: ['lmstudio', 'ollama'], codex: ['lmstudio', 'ollama'], agy: [] };

package/dist/harnesses/replay-events.js

@@ -0,0 +1,57 @@
+// Feeds the stdout.log of an old Claude execution through the adapter (ADR 0006): prints its events as JSON lines,
+// or, with --db and --execution, stores them for an execution that ran before events existed.
+//   pnpm replay:events <stdout.log> [--db <carrier.db> --execution <id>]
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { eq } from 'drizzle-orm';
+import { createEventState } from '../execution/events.js';
+import { openDatabase } from '../storage/db.js';
+import { executionEvents, recordEvents } from '../storage/events.js';
+import { executions } from '../storage/executions.js';
+import { parseClaudeEvents } from './claude.js';
+export function replayEvents(log) {
+    const state = createEventState();
+    return log.split('\n').flatMap((line) => parseClaudeEvents(line, state));
+}
+class UsageError extends Error {
+}
+function run(argv, out) {
+    const { values, positionals } = parseArgs({ args: argv, options: { db: { type: 'string' }, execution: { type: 'string' } }, allowPositionals: true });
+    const [file, ...extra] = positionals;
+    if (file === undefined || extra.length > 0 || (values.db === undefined) !== (values.execution === undefined)) {
+        throw new UsageError('usage: replay-events <stdout.log> [--db <carrier.db> --execution <id>]');
+    }
+    if (!existsSync(file))
+        throw new Error(`cannot read ${file}: no such file`);
+    const events = replayEvents(readFileSync(file, 'utf8'));
+    if (values.db === undefined || values.execution === undefined) {
+        for (const event of events)
+            out(JSON.stringify(event));
+        return;
+    }
+    if (!existsSync(values.db))
+        throw new Error(`cannot open ${values.db}: no such file`); // openDatabase would create an empty one
+    const db = openDatabase(values.db);
+    try {
+        if (!db.select().from(executions).where(eq(executions.executionId, values.execution)).get())
+            throw new Error(`no execution ${values.execution} in ${values.db}`);
+        if (db.select().from(executionEvents).where(eq(executionEvents.executionId, values.execution)).limit(1).get()) {
+            throw new Error(`execution ${values.execution} already has events: nothing was stored`);
+        }
+        // The log has no time for most lines: the time the log was last written is the closest there is.
+        recordEvents(db, values.execution, events, statSync(file).mtimeMs);
+        out(`stored ${events.length} events for ${values.execution}`);
+    }
+    finally {
+        db.$client.close();
+    }
+}
+if (import.meta.main) {
+    try {
+        run(process.argv.slice(2), (line) => console.log(line));
+    }
+    catch (e) {
+        console.error(`replay-events: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(e instanceof UsageError ? 2 : 1);
+    }
+}

package/dist/integrations/available-repos.js

@@ -0,0 +1,29 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { repoNamePattern } from '../config/schema.js';
+export const pageSize = 30;
+/**
+ * One page of the repos the gh login can reach, newest push first: the raw count of the page on the first line, then one repo per
+ * line (tab separated), archived and disabled left out. `push` (the engine's picker, the default) keeps what the login can push to;
+ * `read` (the chat) also takes the repos it is only a collaborator on, and keeps every one it can read.
+ */
+export const ghReposArgs = (page, scope = 'push') => [
+    'api',
+    `user/repos?affiliation=${scope === 'push' ? 'owner,organization_member' : 'owner,collaborator,organization_member'}&sort=pushed&per_page=${pageSize}&page=${page}`,
+    '--jq',
+    `(length | tostring), (.[] | select(.archived or .disabled | not) | ${scope === 'push' ? 'select(.permissions.push) | ' : ''}[.full_name, .private, .pushed_at // ""] | @tsv)`,
+];
+/** `hasMore` follows the raw page (it came back full), not what survived the filter. A line that does not fit (a name that is not `owner/name`) is dropped. */
+export function parseRepos(output) {
+    const [count, ...lines] = output.split('\n');
+    const repos = lines.flatMap((line) => {
+        const [name = '', isPrivate, pushedAt] = line.split('\t');
+        return repoNamePattern.test(name) ? [{ name, private: isPrivate === 'true', pushedAt: pushedAt || null }] : [];
+    });
+    return { repos, hasMore: Number(count) === pageSize };
+}
+/** One page, without blocking the engine; throws when gh is missing, not logged in, offline or past `timeoutMs`. */
+export async function listAvailableRepos(page, timeoutMs, scope = 'push') {
+    const { stdout } = await promisify(execFile)('gh', ghReposArgs(page, scope), { encoding: 'utf8', timeout: timeoutMs });
+    return parseRepos(stdout);
+}

package/dist/integrations/forge-cwd.js

@@ -0,0 +1,27 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { repoNamePattern } from '../config/schema.js';
+/**
+ * Where to run `gh` / Forge for a repo. Forge picks the App installation from the `origin` of the cwd, so it must
+ * be a repo under the right owner: the managed clone (`<repos>/<owner>/<name>`) once it exists, and before the
+ * first clone (the first poll comes first) a stub repo whose only content is that `origin`.
+ */
+export function forgeCwd(places, remoteUrl = (repo) => `https://github.com/${repo}.git`) {
+    return (repo) => {
+        if (!repoNamePattern.test(repo))
+            throw new Error(`invalid repo "${repo}", expected owner/name`);
+        const clone = join(places.repos, repo);
+        if (existsSync(join(clone, '.git')))
+            return clone;
+        const stub = join(places.state, 'forge-cwd', repo);
+        if (!existsSync(join(stub, '.git'))) {
+            mkdirSync(stub, { recursive: true });
+            execFileSync('git', ['init', '-q'], { cwd: stub });
+        }
+        // Separate step: a process killed between init and here leaves a stub that the next call completes.
+        if (spawnSync('git', ['remote', 'get-url', 'origin'], { cwd: stub }).status !== 0)
+            execFileSync('git', ['remote', 'add', 'origin', remoteUrl(repo)], { cwd: stub });
+        return stub;
+    };
+}

package/dist/integrations/github-graphql.js

@@ -0,0 +1,216 @@
+import { z } from 'zod';
+import { redact } from '../logging/redact.js';
+// What the GraphQL answers look like, as recorded in docs/research/macos-app-github-graphql.md.
+// The queries live in that note; these schemas decode what they return.
+/** Slices read per epic; more than this and the reply says it is partial. */
+export const SLICE_LIMIT = 100;
+/** Review threads read per pull request; more than this and the reply says it is partial. */
+export const THREAD_LIMIT = 100;
+/** Longest first line of a thread's opening comment that is kept. */
+const FIRST_LINE_MAX = 160;
+const rateLimit = z.object({ cost: z.int().positive(), remaining: z.int().nonnegative(), limit: z.int().positive(), resetAt: z.string() });
+const slice = z.object({
+    number: z.int().positive(),
+    title: z.string(),
+    state: z.enum(['OPEN', 'CLOSED']),
+    stateReason: z.enum(['COMPLETED', 'NOT_PLANNED', 'REOPENED', 'DUPLICATE']).nullable(),
+    closedAt: z.string().nullable(),
+    assignees: z.object({ nodes: z.array(z.object({ login: z.string() })) }),
+    // Closed blockers are listed too: a slice waits only while one of them is OPEN.
+    blockedBy: z.object({
+        nodes: z.array(z.object({ number: z.int().positive(), state: z.enum(['OPEN', 'CLOSED']), repository: z.object({ nameWithOwner: z.string() }) })),
+    }),
+    // Added after the spike: what mentions the slice. Absent in the recorded answers, so it defaults to nothing.
+    timelineItems: z.object({ nodes: z.array(z.object({ source: z.object({ __typename: z.string(), number: z.int().positive().optional(), headRefName: z.string().optional(), state: z.enum(['OPEN', 'CLOSED', 'MERGED']).optional(), isDraft: z.boolean().optional(), mergedAt: z.string().nullable().optional() }) })) }).default({ nodes: [] }),
+});
+export const epicSlicesResponse = z.object({
+    data: z.object({
+        rateLimit,
+        repository: z.object({
+            issue: z.object({
+                number: z.int().positive(),
+                title: z.string(),
+                state: z.enum(['OPEN', 'CLOSED']),
+                labels: z.object({ nodes: z.array(z.object({ name: z.string() })) }),
+                subIssuesSummary: z.object({ total: z.int().nonnegative(), completed: z.int().nonnegative(), percentCompleted: z.int().nonnegative() }),
+                subIssues: z.object({ pageInfo: z.object({ hasNextPage: z.boolean() }), nodes: z.array(slice) }),
+            }),
+        }),
+    }),
+});
+const checkCountsByState = z.array(z.object({ state: z.string(), count: z.int().nonnegative() }));
+/** Null when the commit has no checks at all: that is "no checks", never "pending". */
+const statusCheckRollup = z
+    .object({
+    state: z.enum(['SUCCESS', 'FAILURE', 'ERROR', 'PENDING', 'EXPECTED']),
+    contexts: z.object({
+        checkRunCount: z.int().nonnegative(),
+        statusContextCount: z.int().nonnegative(),
+        checkRunCountsByState: checkCountsByState,
+        statusContextCountsByState: checkCountsByState,
+    }),
+})
+    .nullable();
+const reviewThread = z.object({
+    id: z.string(),
+    isResolved: z.boolean(),
+    isOutdated: z.boolean(),
+    path: z.string(),
+    line: z.int().nullable(), // null when the thread is outdated
+    comments: z.object({
+        totalCount: z.int().nonnegative(),
+        nodes: z.array(z.object({ url: z.string(), body: z.string(), author: z.object({ login: z.string(), __typename: z.string() }).nullable() })).min(1),
+    }),
+});
+export const pullRequestResponse = z.object({
+    data: z.object({
+        rateLimit,
+        repository: z.object({
+            pullRequest: z.object({
+                number: z.int().positive(),
+                url: z.string(),
+                isDraft: z.boolean(),
+                state: z.enum(['OPEN', 'CLOSED', 'MERGED']),
+                baseRefName: z.string(),
+                headRefName: z.string(),
+                headRefOid: z.string(),
+                mergeable: z.enum(['MERGEABLE', 'CONFLICTING', 'UNKNOWN']),
+                mergeStateStatus: z.enum(['CLEAN', 'DIRTY', 'BLOCKED', 'BEHIND', 'UNSTABLE', 'HAS_HOOKS', 'UNKNOWN']),
+                reviewDecision: z.enum(['APPROVED', 'CHANGES_REQUESTED', 'REVIEW_REQUIRED']).nullable(),
+                additions: z.int().nonnegative(),
+                deletions: z.int().nonnegative(),
+                changedFiles: z.int().nonnegative(),
+                commits: z.object({ totalCount: z.int().nonnegative() }),
+                lastCommit: z.object({ nodes: z.array(z.object({ commit: z.object({ statusCheckRollup }) })) }),
+                // Added after the spike: absent in the recorded answers, so it defaults to no threads.
+                reviewThreads: z.object({ pageInfo: z.object({ hasNextPage: z.boolean() }), nodes: z.array(reviewThread) }).default({ pageInfo: { hasNextPage: false }, nodes: [] }),
+            }),
+        }),
+    }),
+});
+const checkContext = z.discriminatedUnion('__typename', [
+    z.object({ __typename: z.literal('CheckRun'), name: z.string(), status: z.string(), conclusion: z.string().nullable() }),
+    z.object({ __typename: z.literal('StatusContext'), context: z.string(), state: z.string() }),
+]);
+export const failingCheckResponse = z.object({
+    data: z.object({
+        rateLimit,
+        repository: z.object({
+            pullRequest: z.object({
+                number: z.int().positive(),
+                state: z.enum(['OPEN', 'CLOSED', 'MERGED']),
+                mergeStateStatus: z.string(),
+                lastCommit: z.object({
+                    nodes: z.array(z.object({
+                        commit: z.object({
+                            statusCheckRollup: z
+                                .object({
+                                state: z.string(),
+                                contexts: z.object({
+                                    checkRunCount: z.int().nonnegative(),
+                                    statusContextCount: z.int().nonnegative(),
+                                    pageInfo: z.object({ hasNextPage: z.boolean() }),
+                                    nodes: z.array(checkContext),
+                                }),
+                            })
+                                .nullable(),
+                        }),
+                    })),
+                }),
+            }),
+        }),
+    }),
+});
+/** The epic's slices with their blockers and the pull requests that mention them; the schemas above decode its answer. Cost 2 for 52 slices. */
+export const epicSlicesQuery = `query($owner: String!, $name: String!, $number: Int!) {
+  rateLimit { cost remaining limit resetAt }
+  repository(owner: $owner, name: $name) {
+    issue(number: $number) {
+      number title state
+      labels(first: 20) { nodes { name } }
+      subIssuesSummary { total completed percentCompleted }
+      subIssues(first: ${SLICE_LIMIT}) {
+        pageInfo { hasNextPage }
+        nodes {
+          number title state stateReason closedAt
+          assignees(first: 3) { nodes { login } }
+          blockedBy(first: 20) { nodes { number state repository { nameWithOwner } } }
+          timelineItems(first: 10, itemTypes: [CROSS_REFERENCED_EVENT]) { nodes { ... on CrossReferencedEvent { source { __typename ... on PullRequest { number headRefName state isDraft mergedAt } } } } }
+        }
+      }
+    }
+  }
+}`;
+/**
+ * Closed as completed is merged (`closed`), closed any other way is skipped; open and assigned or with a pull request is working,
+ * open with an open blocker is waiting, otherwise ready to start. A closed blocker does not hold a slice back.
+ */
+export function sliceOf(s) {
+    const blockedBy = s.blockedBy.nodes.filter((b) => b.state === 'OPEN').map((b) => b.number);
+    // The slice's own pull request is the newest mention whose branch is `<feature>/<slice>-<name>`; the timeline also lists pull requests that only cite it (a sibling's, the final one).
+    const own = s.timelineItems.nodes.findLast(({ source }) => source.__typename === 'PullRequest' && source.headRefName?.split('/').pop()?.startsWith(`${s.number}-`))?.source;
+    const prNumber = own?.number ?? null;
+    const prState = own?.state === undefined ? null : own.state === 'MERGED' ? 'merged' : own.state === 'CLOSED' ? 'closed' : own.isDraft ? 'draft' : 'open';
+    const prMergedAt = own?.mergedAt ? Date.parse(own.mergedAt) : null;
+    const assignee = s.assignees.nodes[0]?.login ?? null;
+    let state;
+    if (s.state === 'CLOSED')
+        state = s.stateReason === 'NOT_PLANNED' || s.stateReason === 'DUPLICATE' ? 'skipped' : 'closed';
+    else if (assignee !== null || prNumber !== null)
+        state = 'in_progress';
+    else
+        state = blockedBy.length > 0 ? 'waiting' : 'ready';
+    return { number: s.number, title: s.title, state, blockedBy, assignee, prNumber, prState, prMergedAt, closedAt: s.closedAt === null ? null : Date.parse(s.closedAt) };
+}
+/** A pull request with its checks, merge state, review decision and first hundred review threads; the schema above decodes its answer. Cost 1. */
+export const pullRequestQuery = `query($owner: String!, $name: String!, $number: Int!) {
+  rateLimit { cost remaining limit resetAt }
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      number url isDraft state baseRefName headRefName headRefOid
+      mergeable mergeStateStatus reviewDecision
+      additions deletions changedFiles commits { totalCount }
+      lastCommit: commits(last: 1) { nodes { commit { statusCheckRollup { state
+        contexts(first: 1) { checkRunCount statusContextCount
+          checkRunCountsByState { state count } statusContextCountsByState { state count } } } } } }
+      reviewThreads(first: ${THREAD_LIMIT}) { totalCount pageInfo { hasNextPage }
+        nodes { id isResolved isOutdated path line
+          comments(first: 1) { totalCount nodes { url body author { login __typename } } } } }
+    }
+  }
+}`;
+const failingStates = new Set(['ACTION_REQUIRED', 'CANCELLED', 'FAILURE', 'STARTUP_FAILURE', 'STALE', 'TIMED_OUT', 'ERROR']);
+const passingStates = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED', 'COMPLETED']);
+/** Check runs and status contexts counted together: a state that is neither passing nor failing is still running or waiting. A commit with no rollup has no checks (null), never pending. */
+export function pullRequestOf(response) {
+    const pr = response.data.repository.pullRequest;
+    const rollup = pr.lastCommit.nodes[0]?.commit.statusCheckRollup ?? null;
+    let checks = null;
+    if (rollup !== null) {
+        checks = { passing: 0, failing: 0, pending: 0 };
+        for (const { state, count } of [...rollup.contexts.checkRunCountsByState, ...rollup.contexts.statusContextCountsByState]) {
+            checks[failingStates.has(state) ? 'failing' : passingStates.has(state) ? 'passing' : 'pending'] += count;
+        }
+    }
+    return { number: pr.number, url: pr.url, draft: pr.isDraft, mergeState: pr.mergeStateStatus, reviewDecision: pr.reviewDecision, checks };
+}
+/** The first line of the opening comment is redacted before it is cut, so a token is never left half there. */
+export function threadsOf(response) {
+    const { nodes, pageInfo } = response.data.repository.pullRequest.reviewThreads;
+    const threads = nodes.map((t) => {
+        const first = t.comments.nodes[0];
+        return {
+            id: t.id,
+            path: t.path,
+            line: t.line,
+            resolved: t.isResolved,
+            outdated: t.isOutdated,
+            author: first.author?.login ?? null,
+            bot: first.author?.__typename === 'Bot',
+            firstLine: [...redact(first.body.split(/\r?\n/, 1)[0])].slice(0, FIRST_LINE_MAX).join(''),
+            commentCount: t.comments.totalCount,
+            url: first.url,
+        };
+    });
+    return { threads, truncated: pageInfo.hasNextPage };
+}