stageflow 0.27.0 → 0.30.0

package/dist/runstore/sqlite/migrations/009-trigger-next-run.js

@@ -0,0 +1,19 @@
+import { PACKAGE_VERSION } from "../../../package-meta.js";
+function addNextRunAtColumn(db) {
+    try {
+        db.exec(`ALTER TABLE triggers ADD COLUMN next_run_at TEXT`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (!/duplicate column name/i.test(message))
+            throw err;
+    }
+}
+export const MIGRATION_009 = {
+    version: 9,
+    name: "009_trigger_next_run",
+    minStageflowVersion: PACKAGE_VERSION,
+    up(db) {
+        addNextRunAtColumn(db);
+    },
+};

package/dist/runstore/sqlite/migrations/010-trigger-adapter-state.d.ts

@@ -0,0 +1,7 @@
+import type Database from "better-sqlite3";
+export declare const MIGRATION_010: {
+    version: number;
+    name: string;
+    minStageflowVersion: string;
+    up(db: Database.Database): void;
+};

package/dist/runstore/sqlite/migrations/010-trigger-adapter-state.js

@@ -0,0 +1,17 @@
+import { PACKAGE_VERSION } from "../../../package-meta.js";
+export const MIGRATION_010 = {
+    version: 10,
+    name: "010_trigger_adapter_state",
+    minStageflowVersion: PACKAGE_VERSION,
+    up(db) {
+        db.exec(`
+CREATE TABLE IF NOT EXISTS trigger_adapter_state (
+  trigger_id TEXT NOT NULL,
+  key TEXT NOT NULL,
+  value TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (trigger_id, key)
+);
+`);
+    },
+};

package/dist/runstore/sqlite/migrations/index.js

@@ -6,6 +6,9 @@ import { MIGRATION_004 } from "./004-auto-resume-count.js";
 import { MIGRATION_005 } from "./005-config-origins.js";
 import { MIGRATION_006 } from "./006-pipeline-body-and-caller.js";
 import { MIGRATION_007 } from "./007-projects-registry.js";
+import { MIGRATION_008 } from "./008-triggers-table.js";
+import { MIGRATION_009 } from "./009-trigger-next-run.js";
+import { MIGRATION_010 } from "./010-trigger-adapter-state.js";
 const DEFAULT_MIGRATIONS = [
     MIGRATION_001,
     MIGRATION_002,
@@ -14,6 +17,9 @@ const DEFAULT_MIGRATIONS = [
     MIGRATION_005,
     MIGRATION_006,
     MIGRATION_007,
+    MIGRATION_008,
+    MIGRATION_009,
+    MIGRATION_010,
 ];
 export const CURRENT_SCHEMA_VERSION = DEFAULT_MIGRATIONS[DEFAULT_MIGRATIONS.length - 1].version;
 function throwStoreSchemaTooNew(db, version, maxKnown) {

package/dist/runtime/answerResume.d.ts

@@ -4,6 +4,7 @@ export declare const WAIT_WITHOUT_WORKER_DISPATCH = "stage entered wait without
 export type AnswerResumeAdapterResult = {
     ok: boolean;
     reason?: string;
+    verification?: "failed_retrying";
 };
 export declare function orchestrateAnswerResume(options: {
     prefixMode: "live" | "restart";

package/dist/runtime/answerResume.js

@@ -18,5 +18,7 @@ export async function orchestrateAnswerResume(options) {
             status: 500,
         };
     }
-    return { ok: true };
+    return outcome.verification !== undefined
+        ? { ok: true, verification: outcome.verification }
+        : { ok: true };
 }

package/dist/runtime/completionCheckRunner.d.ts

@@ -72,6 +72,12 @@ export type CompletionCheckRunnerInput = {
     /** Why the runtime could not establish the required pre-stage baseline. */
     checkoutError?: string;
     checklistAttestations?: readonly ChecklistAttestation[];
+    /** Re-runs the Host login check against the stage's own browser session. */
+    browserLogin?: () => Promise<{
+        state: "logged_in" | "logged_out" | "unknown";
+        logged_in: boolean | null;
+        url: string;
+    }>;
     onCheckStart?: (check: CompletionCheck) => Promise<void> | void;
     onCheckComplete?: (result: CompletionCheckResult) => Promise<void> | void;
 };
@@ -118,7 +124,12 @@ export type ChecklistCheckEvidence = {
     missing_items: string[];
     unexpected_items: string[];
 };
-export type CompletionCheckEvidence = CommandCheckEvidence | ArtifactCheckEvidence | PayloadSchemaCheckEvidence | GateCheckEvidence | CheckoutChangesCheckEvidence | ChecklistCheckEvidence;
+export type BrowserLoginCheckEvidence = {
+    kind: "browser_login";
+    state?: "logged_in" | "logged_out" | "unknown";
+    url?: string;
+};
+export type CompletionCheckEvidence = BrowserLoginCheckEvidence | CommandCheckEvidence | ArtifactCheckEvidence | PayloadSchemaCheckEvidence | GateCheckEvidence | CheckoutChangesCheckEvidence | ChecklistCheckEvidence;
 export type CompletionCheckResult = {
     check_id: string;
     check_type: CompletionCheck["type"];

package/dist/runtime/completionCheckRunner.js

@@ -364,6 +364,26 @@ function runChecklistCheck(check, input) {
     }
     return result(check, "passed", evidence);
 }
+async function runBrowserLoginCheck(check, input) {
+    const empty = { kind: "browser_login" };
+    if (input.browserLogin === undefined) {
+        return result(check, "error", empty, "browser_login check requires a browser session");
+    }
+    try {
+        const observed = await input.browserLogin();
+        const evidence = {
+            kind: "browser_login",
+            state: observed.state,
+            url: observed.url,
+        };
+        return observed.logged_in === true
+            ? result(check, "passed", evidence)
+            : result(check, "failed", evidence, `the Host login check still sees a ${observed.state === "unknown" ? "session it cannot confirm" : "logged-out session"}`);
+    }
+    catch (error) {
+        return result(check, "error", empty, error instanceof Error ? error.message : String(error));
+    }
+}
 async function runCheck(check, input) {
     switch (check.type) {
         case "command":
@@ -378,6 +398,8 @@ async function runCheck(check, input) {
             return runCheckoutChangesCheck(check, input);
         case "checklist":
             return runChecklistCheck(check, input);
+        case "browser_login":
+            return runBrowserLoginCheck(check, input);
     }
 }
 /**

package/dist/runtime/credentialBinding.d.ts

@@ -11,6 +11,8 @@ export type ResolveCredentialBindingOptions = {
 };
 export declare function sfOwnedAgentDir(): string;
 export declare function sfOwnedAuthPath(): string;
+export declare const PI_HOME_AUTH_PATH_ENV = "STAGEFLOW_PI_HOME_AUTH_PATH";
+/** A stage worker's HOME is an empty attempt dir, so the Host passes its own Pi auth path through the environment. */
 export declare function piHomeAuthPath(override?: string): string;
 export declare function isUsableAuthFile(authPath: string): boolean;
 export declare function ensureSfOwnedAuthStore(): string;

package/dist/runtime/credentialBinding.js

@@ -11,8 +11,11 @@ export function sfOwnedAgentDir() {
 export function sfOwnedAuthPath() {
     return path.join(sfOwnedAgentDir(), "auth.json");
 }
+export const PI_HOME_AUTH_PATH_ENV = "STAGEFLOW_PI_HOME_AUTH_PATH";
+/** A stage worker's HOME is an empty attempt dir, so the Host passes its own Pi auth path through the environment. */
 export function piHomeAuthPath(override) {
     return (override ??
+        (process.env[PI_HOME_AUTH_PATH_ENV] || undefined) ??
         path.join(os.homedir(), ".pi", "agent", "auth.json"));
 }
 export function isUsableAuthFile(authPath) {

package/dist/runtime/emailSource.d.ts

@@ -0,0 +1,72 @@
+import type { RunStore } from "../runstore/port.js";
+import type { TriggerFireEvent, TriggerSourcePort } from "./triggerPort.js";
+export declare const DEFAULT_EMAIL_RECONNECT_BASE_DELAY_MS = 1000;
+export declare const DEFAULT_EMAIL_RECONNECT_MAX_DELAY_MS = 30000;
+export declare const EMAIL_TEXT_EXCERPT_MAX_CHARS = 2000;
+export type NormalizedEmailMessage = {
+    uid: number;
+    from: string;
+    subject: string;
+    date: string;
+    text: string;
+};
+export type EmailClientConfig = {
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+};
+/**
+ * Narrow, test-friendly seam over "one IMAP/IDLE mailbox connection". The
+ * default implementation adapts `imapflow`'s `ImapFlow`; tests inject a fake
+ * so no real mailbox is ever contacted.
+ */
+export type EmailImapClient = {
+    connect(): Promise<{
+        uidNext: number;
+    }>;
+    idle(): void;
+    fetchNewMessages(sinceUid: number): Promise<NormalizedEmailMessage[]>;
+    close(): Promise<void>;
+    onExists(listener: () => void): void;
+    onClose(listener: () => void): void;
+    onError(listener: (err: Error) => void): void;
+};
+export type EmailSourceOptions = {
+    store: RunStore;
+    cwd?: string;
+    logError?: (message: string) => void;
+    env?: NodeJS.ProcessEnv;
+    /** Injectable client factory so tests never hit a real mailbox. */
+    createEmailClient?: (config: EmailClientConfig) => EmailImapClient;
+    reconnectBaseDelayMs?: number;
+    reconnectMaxDelayMs?: number;
+};
+/**
+ * `TriggerSourcePort` adapter for `event`-kind triggers whose `event.source`
+ * starts with `email.`. Unlike the poll-based adapters this one is push-based:
+ * on `start()` it groups triggers by distinct mailbox (`host`+`port`+`user`),
+ * opens exactly one real IMAP/IDLE connection per mailbox regardless of how
+ * many triggers watch it, and reacts to the server's new-message
+ * notification instead of ticking on an interval. A dropped connection
+ * reconnects with bounded exponential backoff rather than going dark.
+ */
+export declare class EmailSource implements TriggerSourcePort {
+    private readonly store;
+    private readonly cwd;
+    private readonly logError;
+    private readonly env;
+    private readonly createEmailClient;
+    private readonly reconnectBaseDelayMs;
+    private readonly reconnectMaxDelayMs;
+    private readonly connections;
+    private stopped;
+    constructor(options: EmailSourceOptions);
+    start(onFire: (event: TriggerFireEvent) => Promise<void>): Promise<void>;
+    stop(): Promise<void>;
+    private discover;
+    private connectMailbox;
+    private scheduleReconnect;
+    private processNewMail;
+    private fireSafely;
+}

package/dist/runtime/emailSource.js

@@ -0,0 +1,304 @@
+import path from "node:path";
+import { ImapFlow } from "imapflow";
+import { getCatalogScanPaths } from "../config/browseCatalog.js";
+import { loadTriggerOutcome } from "../config/loadTrigger.js";
+import { catalogContextFromStageflow } from "../config/resolveCatalogContext.js";
+import { readSecretFromEnvOrFile } from "../config/secretFromEnvOrFile.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+import { matchesEventFilter } from "./triggerEventMatch.js";
+export const DEFAULT_EMAIL_RECONNECT_BASE_DELAY_MS = 1_000;
+export const DEFAULT_EMAIL_RECONNECT_MAX_DELAY_MS = 30_000;
+export const EMAIL_TEXT_EXCERPT_MAX_CHARS = 2_000;
+function defaultCreateEmailClient(config) {
+    const client = new ImapFlow({
+        host: config.host,
+        port: config.port,
+        secure: config.port === 993 || config.port === 465,
+        auth: { user: config.user, pass: config.password },
+        logger: false,
+    });
+    return {
+        async connect() {
+            await client.connect();
+            const mailbox = await client.mailboxOpen("INBOX");
+            return { uidNext: mailbox.uidNext };
+        },
+        idle() {
+            void client.idle().catch(() => {
+                // Connection drop surfaces via the 'close'/'error' events below.
+            });
+        },
+        async fetchNewMessages(sinceUid) {
+            if (sinceUid <= 0)
+                return [];
+            const results = [];
+            for await (const msg of client.fetch(`${sinceUid + 1}:*`, { uid: true, envelope: true, bodyParts: ["TEXT"] }, { uid: true })) {
+                if (msg.uid <= sinceUid)
+                    continue;
+                const fromAddr = msg.envelope?.from?.[0];
+                const from = fromAddr?.address ?? fromAddr?.name ?? "";
+                const subject = msg.envelope?.subject ?? "";
+                const rawDate = msg.envelope?.date;
+                const date = rawDate instanceof Date ? rawDate.toISOString() : String(rawDate ?? "");
+                const text = msg.bodyParts?.get("TEXT")?.toString("utf8").slice(0, EMAIL_TEXT_EXCERPT_MAX_CHARS) ?? "";
+                results.push({ uid: msg.uid, from, subject, date, text });
+            }
+            return results;
+        },
+        async close() {
+            try {
+                await client.logout();
+            }
+            catch {
+                client.close();
+            }
+        },
+        onExists(listener) {
+            client.on("exists", () => listener());
+        },
+        onClose(listener) {
+            client.on("close", () => listener());
+        },
+        onError(listener) {
+            client.on("error", (err) => listener(err));
+        },
+    };
+}
+function parseMailboxConfig(definition) {
+    const config = definition.event?.config;
+    const host = config?.host;
+    const port = config?.port;
+    const user = config?.user;
+    const secretRef = config?.secretRef;
+    if (typeof host !== "string" ||
+        host.length === 0 ||
+        typeof port !== "number" ||
+        !Number.isFinite(port) ||
+        typeof user !== "string" ||
+        user.length === 0 ||
+        typeof secretRef !== "string" ||
+        secretRef.length === 0) {
+        return undefined;
+    }
+    return { host, port, user, secretRef };
+}
+function mailboxKeyFor(config) {
+    return `email:${config.host}:${config.port}:${config.user}`;
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * `TriggerSourcePort` adapter for `event`-kind triggers whose `event.source`
+ * starts with `email.`. Unlike the poll-based adapters this one is push-based:
+ * on `start()` it groups triggers by distinct mailbox (`host`+`port`+`user`),
+ * opens exactly one real IMAP/IDLE connection per mailbox regardless of how
+ * many triggers watch it, and reacts to the server's new-message
+ * notification instead of ticking on an interval. A dropped connection
+ * reconnects with bounded exponential backoff rather than going dark.
+ */
+export class EmailSource {
+    store;
+    cwd;
+    logError;
+    env;
+    createEmailClient;
+    reconnectBaseDelayMs;
+    reconnectMaxDelayMs;
+    connections = new Map();
+    stopped = false;
+    constructor(options) {
+        this.store = options.store;
+        this.cwd = options.cwd ?? process.cwd();
+        this.logError =
+            options.logError ??
+                ((message) => {
+                    console.error(message);
+                });
+        this.env = options.env ?? process.env;
+        this.createEmailClient = options.createEmailClient ?? defaultCreateEmailClient;
+        this.reconnectBaseDelayMs = options.reconnectBaseDelayMs ?? DEFAULT_EMAIL_RECONNECT_BASE_DELAY_MS;
+        this.reconnectMaxDelayMs = options.reconnectMaxDelayMs ?? DEFAULT_EMAIL_RECONNECT_MAX_DELAY_MS;
+    }
+    async start(onFire) {
+        this.stopped = false;
+        const ctx = catalogContextFromStageflow(await resolveStageflowContext(this.cwd));
+        const scanPaths = await getCatalogScanPaths(ctx);
+        if (!scanPaths)
+            return;
+        const projectRoot = ctx.projectRoot ?? undefined;
+        const groups = await this.discover(scanPaths.triggerPaths);
+        for (const [mailboxKey, group] of groups) {
+            for (const match of group.matches) {
+                const definitionRef = projectRoot !== undefined
+                    ? path.relative(projectRoot, match.path).replace(/\\/g, "/")
+                    : match.path;
+                await this.store.upsertTrigger({
+                    id: match.definition.id,
+                    definitionRef,
+                    enabled: true,
+                });
+            }
+            await this.connectMailbox(mailboxKey, group, onFire);
+        }
+    }
+    async stop() {
+        this.stopped = true;
+        for (const [mailboxKey, conn] of this.connections) {
+            conn.stopping = true;
+            if (conn.reconnectTimer !== undefined) {
+                clearTimeout(conn.reconnectTimer);
+                conn.reconnectTimer = undefined;
+            }
+            if (conn.client) {
+                try {
+                    await conn.client.close();
+                }
+                catch (err) {
+                    this.logError(`email: closing mailbox "${mailboxKey}" failed: ${errMsg(err)}`);
+                }
+            }
+        }
+        this.connections.clear();
+    }
+    async discover(triggerPaths) {
+        const groups = new Map();
+        for (const triggerPath of triggerPaths) {
+            const outcome = await loadTriggerOutcome(triggerPath);
+            if (!outcome.ok)
+                continue;
+            const definition = outcome.value;
+            if (definition.kind !== "event" || !definition.enabled)
+                continue;
+            const source = definition.event?.source;
+            if (typeof source !== "string" || !source.startsWith("email."))
+                continue;
+            const config = parseMailboxConfig(definition);
+            if (!config) {
+                this.logError(`email: trigger "${definition.id}" has incomplete event.config ` +
+                    `(expected host, port, user, secretRef); skipping`);
+                continue;
+            }
+            const mailboxKey = mailboxKeyFor(config);
+            const group = groups.get(mailboxKey) ?? { config, matches: [] };
+            group.matches.push({ path: triggerPath, definition });
+            groups.set(mailboxKey, group);
+        }
+        return groups;
+    }
+    async connectMailbox(mailboxKey, group, onFire) {
+        let conn = this.connections.get(mailboxKey);
+        if (!conn) {
+            conn = { group, onFire, reconnectAttempt: 0, stopping: false };
+            this.connections.set(mailboxKey, conn);
+        }
+        if (conn.stopping || this.stopped)
+            return;
+        let password;
+        try {
+            password = readSecretFromEnvOrFile(this.env, group.config.secretRef);
+        }
+        catch (err) {
+            this.logError(`email: failed to read secret "${group.config.secretRef}" for mailbox "${mailboxKey}": ${errMsg(err)}`);
+            return;
+        }
+        if (password === undefined) {
+            this.logError(`email: secret "${group.config.secretRef}" is not set for mailbox "${mailboxKey}"; skipping`);
+            return;
+        }
+        const client = this.createEmailClient({
+            host: group.config.host,
+            port: group.config.port,
+            user: group.config.user,
+            password,
+        });
+        conn.client = client;
+        client.onError((err) => {
+            this.logError(`email: mailbox "${mailboxKey}" error: ${errMsg(err)}`);
+        });
+        client.onClose(() => {
+            const current = this.connections.get(mailboxKey);
+            if (this.stopped || !current || current.stopping)
+                return;
+            this.scheduleReconnect(mailboxKey);
+        });
+        client.onExists(() => {
+            void this.processNewMail(mailboxKey).catch((err) => {
+                this.logError(`email: processing new mail for mailbox "${mailboxKey}" failed: ${errMsg(err)}`);
+            });
+        });
+        try {
+            const { uidNext } = await client.connect();
+            const existing = await this.store.getTriggerAdapterState(mailboxKey, "uid");
+            if (existing === null) {
+                await this.store.setTriggerAdapterState(mailboxKey, "uid", String(Math.max(uidNext - 1, 0)));
+            }
+            client.idle();
+            conn.reconnectAttempt = 0;
+        }
+        catch (err) {
+            this.logError(`email: connecting to mailbox "${mailboxKey}" failed: ${errMsg(err)}`);
+            this.scheduleReconnect(mailboxKey);
+        }
+    }
+    scheduleReconnect(mailboxKey) {
+        const conn = this.connections.get(mailboxKey);
+        if (!conn || conn.stopping || this.stopped)
+            return;
+        const attempt = conn.reconnectAttempt;
+        const delay = Math.min(this.reconnectBaseDelayMs * 2 ** attempt, this.reconnectMaxDelayMs);
+        conn.reconnectAttempt = attempt + 1;
+        conn.reconnectTimer = setTimeout(() => {
+            conn.reconnectTimer = undefined;
+            void this.connectMailbox(mailboxKey, conn.group, conn.onFire);
+        }, delay).unref();
+    }
+    async processNewMail(mailboxKey) {
+        const conn = this.connections.get(mailboxKey);
+        if (!conn?.client)
+            return;
+        const watermarkRaw = await this.store.getTriggerAdapterState(mailboxKey, "uid");
+        const sinceUid = watermarkRaw !== null ? Number(watermarkRaw) : 0;
+        const messages = await conn.client.fetchNewMessages(sinceUid);
+        if (messages.length === 0)
+            return;
+        let maxUid = sinceUid;
+        for (const message of messages) {
+            if (message.uid <= sinceUid)
+                continue;
+            if (message.uid > maxUid)
+                maxUid = message.uid;
+            const summary = {
+                from: message.from,
+                subject: message.subject,
+                date: message.date,
+                text: message.text,
+            };
+            for (const { definition } of conn.group.matches) {
+                if (!matchesEventFilter(definition.event?.match, summary))
+                    continue;
+                await this.fireSafely(conn.onFire, definition, message, summary);
+            }
+        }
+        if (maxUid > sinceUid) {
+            await this.store.setTriggerAdapterState(mailboxKey, "uid", String(maxUid));
+        }
+    }
+    async fireSafely(onFire, definition, message, summary) {
+        try {
+            if (definition.task !== undefined) {
+                await onFire({ triggerId: definition.id });
+                return;
+            }
+            const task = {
+                id: `${definition.id}-email-${message.uid}`,
+                goal: `Handle email: ${message.subject}`,
+                input: summary,
+            };
+            await onFire({ triggerId: definition.id, task });
+        }
+        catch (err) {
+            this.logError(`email: firing trigger "${definition.id}" failed: ${errMsg(err)}`);
+        }
+    }
+}

package/dist/runtime/githubPollSource.d.ts

@@ -0,0 +1,86 @@
+import type { RunStore } from "../runstore/port.js";
+import type { TriggerFireEvent, TriggerSourcePort } from "./triggerPort.js";
+export declare const DEFAULT_GITHUB_POLL_INTERVAL_MS = 60000;
+export declare const DEFAULT_GITHUB_TOKEN_SECRET = "GITHUB_TOKEN";
+/** Parse `STAGEFLOW_GITHUB_POLL_INTERVAL_MS`; default 60s; `0` disables. */
+export declare function githubPollIntervalMsFromEnv(env?: NodeJS.ProcessEnv): number;
+export type GithubPullItem = {
+    number: number;
+    title: string;
+    html_url: string;
+    state: string;
+    merged_at: string | null;
+    created_at: string;
+    updated_at: string;
+    user: {
+        login: string;
+    } | null;
+};
+export type GithubPollResponse = {
+    status: number;
+    etag?: string;
+    items: GithubPullItem[];
+};
+/**
+ * Narrow, test-friendly seam over "list PR activity for a repo, conditionally
+ * on an ETag". The default implementation adapts `octokit.rest.pulls.list`;
+ * tests inject a fake so no real GitHub calls happen.
+ */
+export type GithubPollClient = {
+    listPulls(params: {
+        owner: string;
+        repo: string;
+        etag?: string;
+    }): Promise<GithubPollResponse>;
+};
+export declare function defaultCreateGithubClient(token: string): GithubPollClient;
+export type NormalizedGithubEvent = {
+    action: "opened" | "merged" | "closed" | "updated";
+    number: number;
+    title: string;
+    url: string;
+    author: string;
+    repo: string;
+    updatedAt: string;
+};
+export type GithubPollSourceOptions = {
+    store: RunStore;
+    cwd?: string;
+    intervalMs?: number;
+    logError?: (message: string) => void;
+    env?: NodeJS.ProcessEnv;
+    /** Injectable client factory so tests never hit real GitHub. */
+    createGithubClient?: (token: string) => GithubPollClient;
+};
+/**
+ * `TriggerSourcePort` adapter for `event`-kind triggers whose `event.source`
+ * starts with `github.`. Ticks on an interval; each tick re-scans the catalog,
+ * groups triggers by their distinct `event.config.repo` (one API call per repo
+ * per tick regardless of how many triggers watch it), and diffs each repo's
+ * PR list against a persisted ETag + cursor to find genuinely new activity.
+ *
+ * The first tick for a never-before-seen repo only seeds the cursor — it
+ * never fires for a repo's pre-existing PR history, mirroring how
+ * `ScheduleSource` seeds `next_run_at` without firing on first sight.
+ */
+export declare class GithubPollSource implements TriggerSourcePort {
+    private readonly store;
+    private readonly cwd;
+    private readonly intervalMs;
+    private readonly logError;
+    private readonly env;
+    private readonly createGithubClient;
+    private interval;
+    private inFlight;
+    constructor(options: GithubPollSourceOptions);
+    start(onFire: (event: TriggerFireEvent) => Promise<void>): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * One discovery + poll + fire pass. Public so tests can drive it directly
+     * instead of waiting on real interval timers.
+     */
+    tick(onFire: (event: TriggerFireEvent) => Promise<void>): Promise<void>;
+    private discover;
+    private pollRepo;
+    private fireSafely;
+}