@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5682

package/dist/ci-wait/errors.js

@@ -0,0 +1,273 @@
+import { productIdentity } from '../home/identity.js';
+import { TIMER_MAX_SECONDS, TIMER_MIN_SECONDS } from '../contract/index.js';
+import { MESSAGING_OFF } from '../delegation/policy.js';
+import { ASK_LIMITS } from '../contract/index.js';
+/** Safe diagnostics shared by the manager and private transport. Never forward raw errors. */
+const messages = {
+    wait_conflict: 'A different CI wait is already active for this run.',
+    unsupported_host: 'GitHub Enterprise host is not recognized; use a host configured with the existing GitHub authentication.',
+    gh_missing: 'Install GitHub CLI (gh) to wait for CI.',
+    authentication: 'Authenticate GitHub CLI with gh auth login and retry.',
+    inaccessible_pr: 'The pull request is inaccessible; check its URL and GitHub permissions.',
+    capacity: 'CI wait registration capacity is exhausted; retry later.',
+    persistence: 'CI wait could not be saved; check local storage and retry.',
+    query_timeout: 'GitHub metadata lookup timed out; check connectivity and retry.',
+    invalid_request: 'Invalid CI wait arguments.',
+    malformed_data: 'GitHub returned invalid CI metadata; check the pull request and retry.',
+    output_limit: 'GitHub CI metadata exceeded the output limit; inspect the pull request before retrying.',
+    command_failed: 'The GitHub CI query failed; check GitHub CLI connectivity and retry.',
+    unavailable: 'CI tool unavailable: registration failed. Retry from the current session.',
+    unauthorized: 'CI tool unavailable: session capability is missing or revoked. Use the current session tool.',
+    manager_disposed: 'The run manager was disposed. Resume the task in a running cockpit before waiting for CI.',
+    capability_revoked: 'The CI session capability was revoked. Use the current session tool.',
+    run_missing: 'The run no longer exists. Start or resume an existing task before waiting for CI.',
+    run_not_running: 'The run is not running or waiting. Resume it before registering a CI wait.',
+    run_stopping: 'The run is stopping. Wait for it to stop, then resume before registering a CI wait.',
+    session_replaced: 'The session was replaced or there is no active session. Use the current session tool after resuming.',
+    session_closed: 'The agent session is closed. Resume the task before registering a CI wait.',
+    run_cancelled: 'The run was cancelled. Resume it before registering a CI wait.',
+    finish_requested: 'Run finish was requested. Complete that transition before resuming and registering a CI wait.',
+    generation_mismatch: 'This CI tool belongs to an earlier session. Use the current session tool.',
+    worker_wait_pending: 'A worker wait is still pending, including any result awaiting delivery. End your turn to receive its result, then retry the CI wait.',
+    worker_execution_stopped: 'Worker execution has stopped. Ask the parent to resume the worker before waiting for CI.',
+    root_finish_pending: 'The parent is finishing. Complete that transition before resuming and registering a CI wait.',
+    registration_aborted: 'CI registration was interrupted during lookup. Retry from the current turn if a wait is still needed.',
+    turn_changed: 'The agent turn changed during CI lookup. Register the wait again from the current turn.',
+};
+export function ciErrorMessage(code) {
+    return messages[code];
+}
+/** hearsay-tools/cezarion#2397: a launch refused because the lifecycle tools could not start. */
+export function toolsUnavailableMessage(detail, directory) {
+    const where = directory ? `a private socket directory in ${directory}` : 'a private named pipe';
+    const fix = directory ? `Free space in ${directory} or fix its permissions` : 'Fix the cause';
+    return `Cezar tools could not start: ${detail}. Every agent session needs ${where}. ${fix}, then Continue the task.`;
+}
+// hearsay-tools/cezarion#1233: `cezar_wait` refusals. Each names what the agent can do next.
+const waitMessages = {
+    duplicate_deadline: 'Deadline change refused. The retained wait is still active with its original deadline. Do not cancel it to remove a duplicate.',
+    operation_conflict: 'This operation_id belongs to different arguments. Retry the original arguments or use a new operation_id.',
+    outcome_unknown: 'Registration outcome is unknown. Retry the same operation_id and arguments to recover its receipt; do not assume nothing was created or add a fallback wait.',
+    timers_disabled: 'Automatic re-checks are turned off for this workspace (Park until resumed). Do not register a timer; end your turn and the user resumes the task.',
+    wake_budget_spent: 'This run spent its automatic wakes. Do not register another timer; call cezar_ask if you need the user, or end your turn.',
+    capacity: 'Cezar cannot open another wait now: this run has the maximum open waits, or the CI watcher is full. Cancel a wait you no longer need with cezar_cancel_wait, or retry later.',
+    messaging_off: MESSAGING_OFF,
+    denied_scope: 'This run cannot wait on those workers or requests: wait only on workers you own (a parent with the wait permission), or on requests you sent that are still accepted.',
+    // hearsay-tools/cezarion#1446: process waits.
+    exit_file_outside: 'exit_file must be inside the task worktree or the Cezar temp directory that $TMPDIR names, with no symlink leading out. If $TMPDIR is not under .ai/cezar or a cez-agent directory, use a git-ignored path in the worktree. For a command that writes its own status file somewhere else, leave exit_file out: wait on pid alone, and read that file after the wake.',
+    process_not_allowed: 'Cezar cannot wait on that PID: it is Cezar itself or an agent session, which ends only with the session. Pass the `pid` that the job start command printed for the background command.',
+    process_not_owned: 'That PID belongs to another user, so Cezar cannot tell whether it is the process you started. Pass the PID of a command you started yourself.',
+};
+export function waitErrorMessage(code) {
+    return waitMessages[code] ?? messages[code];
+}
+// hearsay-tools/cezarion#1234: `cezar_ask` refusals. A question never meets a CI lookup, so none
+// borrows the CI wording.
+const askMessages = {
+    autonomous_run: 'This is an autonomous run: do not wait for the user. Make a reasonable assumption and continue; the user can steer you at any time.',
+    capacity: 'Cezar cannot open another wait now: this run has the maximum open waits. Cancel a wait you no longer need with cezar_cancel_wait, then ask again.',
+    invalid_request: 'Invalid cezar_ask arguments.',
+    persistence: 'Your question could not be saved; retry once, and if it fails again ask it in your final message.',
+    unavailable: 'Cezar could not show your question now. Retry once; if it fails again, ask it in your final message.',
+    unauthorized: 'This session\'s cezar tools are missing or revoked. Use the current session tool.',
+    manager_disposed: 'The run manager was disposed. Ask your question in your final message.',
+    capability_revoked: 'This session\'s cezar tools were revoked. Use the current session tool.',
+    run_missing: 'The run no longer exists.',
+    run_not_running: 'The run is not running or waiting. Resume it before asking.',
+    run_stopping: 'The run is stopping. End your turn; it stops without your question.',
+    session_replaced: 'The session was replaced or there is no active session. Use the current session tool after resuming.',
+    session_closed: 'The agent session is closed. Resume the task before asking.',
+    run_cancelled: 'The run was cancelled.',
+    finish_requested: 'Finish was already requested for this run. End your turn.',
+    generation_mismatch: 'This tool belongs to an earlier session. Use the current session tool.',
+    worker_wait_pending: 'A worker wait is still pending, including any result awaiting delivery. End your turn to receive its result, then ask again if you still need the user.',
+    worker_execution_stopped: 'Worker execution has stopped. Ask the parent to resume the worker before asking.',
+    root_finish_pending: 'The parent is finishing. End your turn; the parent completes that transition.',
+};
+export function askErrorMessage(code) {
+    return askMessages[code];
+}
+const L = ASK_LIMITS;
+const ASK_FIELDS = `cezar_ask takes context and questions: context of 1–${L.context} characters of Markdown, shown above the card, and 1–${L.questions} questions with unique texts, each with a header of 1–${L.header} characters, a question of 1–${L.question} characters, an optional id of 1–${L.id} characters, and either ${L.minOptions}–${L.maxOptions} options with unique labels of 1–${L.label} characters and descriptions of at most ${L.description} characters, or no options for an open question`;
+/** hearsay-tools/cezarion#1428: a rejected call never reaches the user. hearsay-tools/cezarion#1458:
+ *  the detail cut from a question belongs in `context`, which the user reads above the card. */
+const ASK_CONTEXT = 'The user never sees a rejected call. Put the draft, findings, evidence and option meanings in context, and keep each question short.';
+const ASK_FIELD_RULES = {
+    context: `must be 1–${L.context} characters of Markdown`,
+    questions: `must be a list of 1–${L.questions} questions with unique texts`,
+    question_entry: 'must be an object with a header and a question',
+    id: `must be 1–${L.id} characters`,
+    header: `must be 1–${L.header} characters`,
+    question: `must be 1–${L.question} characters`,
+    options: `must be ${L.minOptions}–${L.maxOptions} options with unique labels, or left out for an open question`,
+    option_entry: 'must be an object with a label and an optional description',
+    label: `must be 1–${L.label} characters`,
+    description: `must be at most ${L.description} characters`,
+    multiSelect: 'must be true or false',
+};
+/** The rule for one failing path: its last field, or the entry of the list an index points into. */
+function askFieldRule(path) {
+    const last = path.at(-1);
+    if (typeof last === 'number')
+        return ASK_FIELD_RULES[path.at(-2) === 'options' ? 'option_entry' : 'question_entry'];
+    return typeof last === 'string' ? ASK_FIELD_RULES[last] : undefined;
+}
+/** Names every failing field with its limit, never the value the agent sent. */
+export function askInvalidInput(error) {
+    const tail = `${ASK_CONTEXT} ${ASK_FIELDS}.`;
+    const issue = error?.issues[0];
+    if (issue?.code === 'unrecognized_keys')
+        return `Unknown field ${issue.keys.map(key => JSON.stringify(key.slice(0, 64))).join(', ')}. ${tail}`;
+    const failures = new Map();
+    for (const entry of error?.issues ?? []) {
+        const rule = entry.path[0] === 'questions' ? askFieldRule(entry.path) : entry.path[0] === 'context' ? ASK_FIELD_RULES.context : undefined;
+        const name = entry.path.filter(part => typeof part === 'string' || typeof part === 'number').join('.');
+        if (rule && !failures.has(name))
+            failures.set(name, `\`${name}\` ${rule}`);
+    }
+    if (failures.size)
+        return `${[...failures.values()].join('; ')}. ${tail}`;
+    return `The arguments must be a JSON object. ${tail}`;
+}
+// hearsay-tools/cezarion#1234: `cezar_done` refusals that name no worker. The worker refusals list
+// their workers and the commands that clear them, so the run manager writes those.
+const doneMessages = {
+    human_question_pending: 'Your question to the user is still unanswered. End your turn to wait for the answer; call cezar_done after it if the task is then complete.',
+    worker_wait_pending: 'A worker wait is still pending, including any result awaiting delivery. End your turn to receive its result, then call cezar_done again.',
+    // Never returned since hearsay-tools/cezarion#1620: every agent step accepts cezar_done.
+    not_final_step: 'This workflow step is not the last one. Call cezar_done again once this step\'s work is complete.',
+    root_finish_pending: 'The parent is finishing. End your turn; the parent completes that transition.',
+    manager_disposed: 'The run manager was disposed. Resume the task in a running cockpit before finishing.',
+    capability_revoked: 'This session\'s cezar tools were revoked. Use the current session tool.',
+    run_missing: 'The run no longer exists.',
+    run_not_running: 'The run is not running or waiting. Resume it before finishing.',
+    run_stopping: 'The run is stopping. End your turn; it stops without cezar_done.',
+    session_replaced: 'The session was replaced or there is no active session. Use the current session tool after resuming.',
+    session_closed: 'The agent session is closed. Resume the task before finishing.',
+    run_cancelled: 'The run was cancelled.',
+    finish_requested: 'Finish was already requested for this run. End your turn.',
+    generation_mismatch: 'This tool belongs to an earlier session. Use the current session tool.',
+    invalid_request: 'Invalid cezar_done arguments.',
+    unavailable: 'Cezar could not accept cezar_done now. Retry once; if it fails again, end your turn and say the task is complete.',
+};
+export function doneErrorMessage(code) {
+    return doneMessages[code];
+}
+const DONE_FIELDS = 'cezar_done takes only an optional summary of at most 2000 characters';
+/** Names the unknown field or the failing summary, never the value the agent sent. */
+export function doneInvalidInput(error) {
+    const issue = error?.issues[0];
+    if (issue?.code === 'unrecognized_keys')
+        return `Unknown field ${issue.keys.map(key => JSON.stringify(key.slice(0, 64))).join(', ')}: ${DONE_FIELDS}.`;
+    if (error?.issues.some(entry => entry.path[0] === 'summary'))
+        return '`summary` must be a string of at most 2000 characters.';
+    return `The arguments must be a JSON object: ${DONE_FIELDS}.`;
+}
+// #781: `cezar_preview_serve` results. Every one carries the agent's next step; none quotes a
+// secret, an environment value or another task's path.
+const EXAMPLE_CALL = '{ "command": "npm run dev -- --port 5173 --strictPort", "port": 5173 }';
+/** The refusals cezar's tool server answers itself; registration codes come from its owner. */
+export function previewRefusal(code) {
+    switch (code) {
+        case 'preview_disabled': return { ok: false, code, message: 'Live preview is not enabled in this cockpit.', hint: 'Do not retry. Tell the user the server command and port so they can open it themselves.' };
+        case 'headless': return { ok: false, code, message: `No cockpit is attached to this run (\`${productIdentity().command} run\`).`, hint: 'Do not retry. Report the command and port in your final message.' };
+        case 'unavailable': return { ok: false, code, message: 'Cezar\'s tool server did not answer.', hint: 'Retry once. If it fails again, continue without preview and report the command and port in your message.' };
+    }
+}
+const FIELD_RULES = {
+    command: 'must be a string of 1 to 1024 characters',
+    port: 'must be an integer between 1 and 65535',
+    cwd: 'must be a path relative to the worktree root',
+    label: 'must be a string of 1 to 48 characters',
+    path: 'must be a path starting with "/"',
+};
+export function previewOversized() {
+    return { ok: false, code: 'invalid_input', message: 'The arguments exceed 16 KiB.', hint: `Send only the documented fields, e.g. ${EXAMPLE_CALL}, and call again.` };
+}
+/** Names the first failing field and its rule, then a valid example call. */
+export function previewInvalidInput(error, input) {
+    const field = error.issues.map(issue => issue.path[0]).find((key) => typeof key === 'string' && key in FIELD_RULES);
+    if (!field) {
+        return { ok: false, code: 'invalid_input', message: 'The arguments must be a JSON object with `command` and `port`.', hint: `Call again with a JSON object, e.g. ${EXAMPLE_CALL}.` };
+    }
+    const value = input !== null && typeof input === 'object' ? input[field] : undefined;
+    const got = value === undefined ? 'nothing' : JSON.stringify(value).slice(0, 64);
+    return {
+        ok: false,
+        code: 'invalid_input',
+        message: `\`${field}\` ${FIELD_RULES[field]} (got ${got}).`,
+        hint: `"${field}" ${FIELD_RULES[field]}. A valid call: ${EXAMPLE_CALL}. Fix the field and call again.`,
+    };
+}
+// hearsay-tools/cezarion#1233: `cezar_wait` and `cezar_cancel_wait` refusals name the first
+// failing field and its rule, never the value the agent sent.
+const WAIT_FIELD_RULES = {
+    // hearsay-tools/cezarion#1425: an agent still sending kind "ci" learns the new spelling here.
+    kind: 'must be "pr", "worker", "request", "peer", "timer" or "process" (kind "ci" was replaced by kind "pr"); ask the user with cezar_ask',
+    pr: 'must be an HTTPS GitHub pull request URL (kind "pr")',
+    until: 'must be "checks", "merge" or "merge_or_blocked" (kind "pr")',
+    wake_on_conflict: 'must be true or false (kind "pr")',
+    timeout_seconds: 'must be an integer between 1 and 7200 (kind "pr" or "process") or between 1 and 1800 (kind "worker", "request" or "peer")',
+    worker_ids: 'must be 1 to 32 unique worker ids you own (kind "worker")',
+    request_ids: 'must be 1 to 32 unique ids of requests you sent (kind "request")',
+    peer_ids: 'must be 1 to 32 unique ids of peer root tasks in this project (kind "peer")',
+    mode: 'must be "one", "any" or "all"; "one" takes exactly one id (kind "worker" or "request")',
+    seconds: `must be an integer between ${TIMER_MIN_SECONDS} and ${TIMER_MAX_SECONDS} (kind "timer")`,
+    note: 'must be a string of at most 512 characters (kind "timer" or "process")',
+    pid: 'must be an integer of at least 2: the `pid` that the job start command printed (kind "process")',
+    exit_file: 'must be a path of 1 to 4096 characters (kind "process")',
+    wait_id: 'must be a wait_id that cezar_wait answered',
+};
+const WAIT_FIELDS = 'kind "pr" takes pr, until, wake_on_conflict and timeout_seconds; kind "worker" takes worker_ids, mode and timeout_seconds; kind "request" takes request_ids, mode and timeout_seconds; kind "peer" takes peer_ids and timeout_seconds; kind "timer" takes seconds and note; kind "process" takes pid, exit_file, timeout_seconds and note';
+export function waitInvalidInput(error) {
+    const issue = error?.issues[0];
+    if (issue?.code === 'unrecognized_keys')
+        return `Unknown field ${issue.keys.map(key => JSON.stringify(key.slice(0, 64))).join(', ')}: ${WAIT_FIELDS}.`;
+    const field = error?.issues.map(entry => entry.path[0]).find((key) => typeof key === 'string' && key in WAIT_FIELD_RULES);
+    if (field)
+        return `\`${field}\` ${WAIT_FIELD_RULES[field]}.`;
+    return `The arguments must be a JSON object: ${WAIT_FIELDS}.`;
+}
+// hearsay-tools/cezarion#1465: `cezar_schedule_task` and `cezar_scheduled_tasks` refusals.
+const scheduleMessages = {
+    automations_off: 'Automations are off in this cockpit (CEZ_AUTOMATIONS=0), so Cezar cannot schedule a task. Tell the user.',
+    unavailable: 'Cezar could not reach its scheduler for this session. Tell the user; scheduling needs a running cockpit.',
+};
+export function scheduleRefusal(code, message) {
+    return { ok: false, code, message: message ?? scheduleMessages[code] ?? 'Invalid arguments.' };
+}
+const SCHEDULE_FIELD_RULES = {
+    action: 'must be "list", "show", "update", "pause", "enable" or "cancel"',
+    id: 'must be the id of a one-time schedule a list or a create answered',
+    archived: 'must be "include" or "only"',
+    name: 'must be a string of 1 to 200 characters',
+    prompt: 'must be a string of 1 to 100000 characters',
+    at: 'must be a UTC time YYYY-MM-DDTHH:MMZ; give at or delay, not both',
+    delay: 'must be a duration such as 30m, 6h or 7d; give at or delay, not both',
+    latest_start: 'must be a duration such as 30m, 6h or 7d',
+    workflow: 'must be a workflow name',
+    runner: 'must be a runner name',
+    model: 'must be a model id',
+    effort: 'must be an effort level',
+    enable: 'must be true or false',
+};
+/** Names the unknown field or the first failing field and its rule, never the value sent. */
+export function scheduleInvalidInput(error) {
+    const issue = error?.issues[0];
+    if (issue?.code === 'unrecognized_keys')
+        return `Unknown field ${issue.keys.map(key => JSON.stringify(key.slice(0, 64))).join(', ')}.`;
+    const field = error?.issues.map(entry => entry.path[0]).find((key) => typeof key === 'string' && key in SCHEDULE_FIELD_RULES);
+    if (field)
+        return `\`${field}\` ${SCHEDULE_FIELD_RULES[field]}.`;
+    return 'The arguments must be a JSON object.';
+}
+/** A safe refusal shared by tool and delegation transports. */
+export class WaitDeadlineConflict extends Error {
+    retainedWait;
+    code = 'duplicate_deadline';
+    constructor(retainedWait) {
+        super(`Deadline change refused. Wait ${retainedWait.id} remains active until ${'deadline' in retainedWait ? retainedWait.deadline : 'its original deadline'}. Do not cancel it to remove a duplicate.`);
+        this.retainedWait = retainedWait;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/ci-wait/errors.js.map

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

package/dist/ci-wait/github.d.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import { type GithubMergeRequest } from './merge-progress.ts';
+import { type CiPrIdentity, type CiWaitErrorCode } from '../contract/index.js';
+export declare const CI_QUERY_TIMEOUT_MS = 10000;
+/** `gh pr checks --watch --interval`, in seconds. Not the query timeout. */
+export declare const CI_WATCH_INTERVAL_SECONDS = 30;
+export declare const CI_QUERY_LIMIT = 4;
+export declare const CI_OUTPUT_LIMIT: number;
+export declare const CI_TERMINATE_MS = 2000;
+export declare class CiGithubError extends Error {
+    readonly code: CiWaitErrorCode;
+    readonly transient: boolean;
+    constructor(code: CiWaitErrorCode, message: string, transient?: boolean);
+}
+/** FIFO permits; aborted queued requests never consume a slot. */
+export declare class CiSemaphore {
+    private readonly limit;
+    private active;
+    private readonly queue;
+    constructor(limit: number);
+    acquire(signal: AbortSignal): Promise<() => void>;
+    private release;
+}
+export declare const CI_PROCESS_WRAPPER: string;
+export type CiCommandResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+export type CiCommandOptions = {
+    file: string;
+    args: string[];
+};
+/** Environment stays inherited, matching the existing forge gh resolver (including GH_TOKEN/GITHUB_TOKEN). */
+export declare function runCiCommand(command: CiCommandOptions, signal: AbortSignal, discardOutput?: boolean, env?: NodeJS.ProcessEnv, cwd?: string): Promise<CiCommandResult>;
+declare const metadataSchema: z.ZodObject<{
+    url: z.ZodString;
+    number: z.ZodNumber;
+    headRefOid: z.ZodString;
+    mergeable: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<"CONFLICTING" | "MERGEABLE" | "UNKNOWN", string | null | undefined>>;
+    mergeStateStatus: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+}, z.core.$strip>;
+export type GithubPrMetadata = Pick<z.infer<typeof metadataSchema>, 'mergeable' | 'mergeStateStatus'> & {
+    headSha: string;
+};
+export type GithubPrMergeState = GithubPrMetadata & {
+    state: 'OPEN' | 'CLOSED' | 'MERGED';
+    mergedAt?: string;
+    mergeCommitSha?: string;
+};
+export declare const githubChecksSchema: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    state: z.ZodString;
+    link: z.ZodString;
+    bucket: z.ZodEnum<{
+        cancel: "cancel";
+        fail: "fail";
+        pass: "pass";
+        pending: "pending";
+        skipping: "skipping";
+    }>;
+}, z.core.$strip>>;
+export type GithubCheck = z.infer<typeof githubChecksSchema>[number];
+/** One bounded workflow query shared by CI waits and strict completion merging. */
+export declare function activeWorkflowRunsArgs(pr: Pick<CiPrIdentity, 'repository' | 'headSha'>): string[];
+export declare function parseActiveWorkflowRuns(text: string): boolean;
+export declare class GithubCiClient {
+    private readonly queries;
+    private readonly command;
+    private readonly env;
+    private readonly cwd?;
+    constructor(options?: {
+        command?: CiCommandOptions;
+        env?: NodeJS.ProcessEnv;
+        cwd?: string | undefined;
+    });
+    /**
+     * One bounded gh query. An outcome query waits for one of the shared query permits; a progress
+     * query (`permit: false`) takes none, and its caller bounds how many run.
+     */
+    private query;
+    /** Run one gh command under a held query permit. */
+    protected runCommand(args: string[], signal: AbortSignal): Promise<CiCommandResult>;
+    private readMetadata;
+    resolve(pr: string, signal: AbortSignal): Promise<CiPrIdentity>;
+    metadata(pr: CiPrIdentity, signal: AbortSignal): Promise<GithubPrMetadata>;
+    /** The PR's state for a merge wait, in one bounded query with its head and mergeability. */
+    mergeState(pr: CiPrIdentity, signal: AbortSignal): Promise<GithubPrMergeState>;
+    /** Opt-in merge supervision: current pending state and its last lifecycle event, one bounded read. */
+    mergeProgress(pr: CiPrIdentity, signal: AbortSignal): Promise<GithubPrMergeState & {
+        mergeRequest: GithubMergeRequest;
+    }>;
+    head(pr: CiPrIdentity, signal: AbortSignal): Promise<string>;
+    hasActiveRuns(pr: CiPrIdentity, signal: AbortSignal): Promise<boolean>;
+    checks(pr: CiPrIdentity, signal: AbortSignal): Promise<GithubCheck[]>;
+    /**
+     * A checks read for the activity view's progress (spec 2026-11-05-live-activity-view). It takes
+     * no shared query permit, so outcome queries always have all of them; it keeps its own ten-second
+     * bound. The caller runs at most one at a time.
+     */
+    progressChecks(pr: CiPrIdentity, signal: AbortSignal): Promise<GithubCheck[]>;
+    private readChecks;
+    watch(pr: CiPrIdentity, signal: AbortSignal): Promise<void>;
+}
+export {};