@aivi/tracker-github 0.0.0-stage → 0.0.0

package/dist/probe.d.ts

@@ -0,0 +1,104 @@
+import type { PluginSetupContext, Store } from '@aivi/plugin';
+export declare const probeWindowMs: () => number;
+/** The events GitHub posts when a person installs the app or approves its
+ *  grant — the `aivi add` probe's signal, replayed from the delivery history
+ *  (an older install posts nothing while the installer watches). */
+export declare const INSTALLATION_EVENTS: Set<string>;
+/** One payload as the live line says it, in GitHub's own words, naming the
+ *  ticket it is about — during a test several issues can be in play. The
+ *  status our side answered with is left out on purpose: with the module not
+ *  yet loaded nothing can answer 2xx, and the delivery arriving is the point. */
+/** A webhook payload as the probe reads it: like tracker.ts, payloads are
+ *  `unknown` until narrowed — the probe only ever asks for these fields.
+ *  Exported because the waits' signatures name it (fallow private-type-leak). */
+export type ProbePayload = {
+    action?: string;
+    changes?: {
+        field_name?: string;
+        field_value?: {
+            field_name?: string;
+        };
+    };
+    projects_v2_item?: {
+        content_node_id?: string;
+    };
+    repository?: {
+        full_name?: string;
+    };
+    issue?: {
+        number?: number;
+    };
+};
+/** Whether the live aivi answers its health endpoint — the same test Linear's
+ *  installer and the CLI make: `GET /health` on the **listen** URL, whatever
+ *  its version. A raw-read config.json can lack the schema defaults, so the
+ *  defaults are filled here: bind 127.0.0.1, port 4100. Pure of prompts, and
+ *  `up` is re-asked on every retry. */
+export declare function hostIsUp(fetch: (url: string, init?: RequestInit) => Promise<Response>, host: {
+    bind?: string | undefined;
+    port?: number | undefined;
+} | undefined): Promise<boolean>;
+/** The health gate as a choice (ruled 2026-10-07): silence is not a stop, it
+ *  is a fork. Retry re-asks; continue skips the waits and says so — the
+ *  installer still writes its configuration, with UNVERIFIED in the summary. */
+export declare function gateHost(prompts: PluginSetupContext['prompts'], up: () => Promise<boolean>): Promise<boolean>;
+/** The newest diary row id right now. Whatever exists before a test starts is
+ *  nobody's business; anything the test draws lands with a larger id. */
+export declare const latestId: (store: Store) => number;
+/** What one wait saw in the diary. */
+export interface Diaried {
+    /** Verified deliveries this wait accepts — its proof. */
+    mine: number;
+    /** Verified deliveries about anything else: the URL and secret work; the
+     *  events ticked on the webhook decide what arrives. */
+    others: number;
+    /** The diary cursor to hand to the next wait. */
+    last: number;
+}
+/**
+ * Watch the diary until one verified delivery `accepts` lands, `about` names
+ * the thing under test, or `ms` has passed. A wait that passes is not made to
+ * sit out its window; the window is what a failure needs. Every verified
+ * delivery is said the moment it lands, whatever it names.
+ */
+export declare function waitDiary(store: Store, watch: {
+    path: string;
+    secret: string;
+    windowMs: number;
+    accepts: (event: string, payload: ProbePayload) => boolean;
+    about: (event: string, payload: ProbePayload) => boolean;
+}, cursor: number, say: (line: string) => void): Promise<Diaried>;
+/** Watch for the board probe's signals on one issue until all `asked` have
+ *  landed or the window passes. Each landing is said the moment it arrives —
+ *  the live line names what just came in. A signal already landed is never
+ *  counted twice; the window is what a missing signal needs. */
+export declare function waitForSignals(store: Store, watch: {
+    path: string;
+    secret: string;
+    windowMs: number;
+    asked: string[];
+    about: (event: string, payload: ProbePayload) => boolean;
+}, cursor: number, say: (line: string) => void): Promise<{
+    landed: Set<string>;
+    last: number;
+}>;
+/** Whether a delivery is about the probe issue. `issue_comment` names it by
+ *  `issue.number`; an `issues` delivery carries its number inside `issue`
+ *  too — GitHub answers no top-level one (the live ledger says so). A
+ *  `projects_v2_item` delivery names neither repo nor number: its payload
+ *  carries no `repository` at all (keys: action, changes, installation,
+ *  organization, projects_v2_item, sender — the live ledger says so), so
+ *  the content's globally unique node id is the whole referee. Requiring a
+ *  repository there filtered every board delivery as foreign and the wait
+ *  sat out its window on signals it already held. */
+export declare const aboutIssue: (repoId: string, number: number, issueNodeId: string) => (event: string, payload: ProbePayload) => boolean;
+/** The board probe's verdict, pure: which signals landed, which did not, and
+ *  what the missing one means. A signal never paid for (a board with one open
+ *  Status option cannot show a move) is said as skipped, not as a failure. */
+export declare function boardProbeVerdict(landed: Set<string>, asked: string[], windowMs: number): {
+    pass: boolean;
+    detail: string;
+};
+/** The remedy line when the health gate's choice was made and the waits were
+ *  skipped: named once, in the summary, in the same words both installers use. */
+export declare const UNVERIFIED = "UNVERIFIED \u2014 no live aivi watched, so \u201CGitHub can reach this machine\u201D was not proved";

package/dist/probe.js

@@ -0,0 +1,312 @@
+/** The probe machinery both installers share: the health gate with its choice,
+ *  and the diary waits. The installer is a second process; it proves a webhook
+ *  by watching what the **live aivi** records in its request diary — so a live
+ *  aivi is needed for the waits, and the waits are what the choice is about:
+ *
+ *  ```
+ *  ● I started the server. Retry
+ *  ○ Continue anyway — do not verify the webhook
+ *  ```
+ *
+ *  Continuing writes everything and says UNVERIFIED: the unverified fact is
+ *  precisely “GitHub can reach this machine”, and it is said that way, never
+ *  as a claimed success. Every delivery is verified with the module's own seal
+ *  check before it counts: GitHub signs the raw bytes, and the diary stores
+ *  what arrived. A delivery that fails the check ends the wait at once — the
+ *  secret would be wrong for every delivery, so waiting cannot help.
+ */
+import { hostUrl } from '@aivi/core';
+import { verifyWebhookSignature } from '@aivi/github';
+/** How long the diary is watched when a check cannot pass: silence is a
+ *  result too, and only a waited-out silence proves it. Tests shorten the
+ *  window (AIVI_PROBE_WINDOW_MS, shared with the Linear installer); people
+ *  get the honest cap. */
+const DEFAULT_WINDOW_MS = 90_000;
+export const probeWindowMs = () => Number(process.env.AIVI_PROBE_WINDOW_MS ?? DEFAULT_WINDOW_MS);
+/** The installer is a second process and file events do not report SQLite's WAL
+ *  writes (macOS never mentions them, measured 2026-09-26), so the diary is
+ *  re-read on this quiet interval — one query on an indexed column. */
+const POLL_MS = 2_000;
+/** The events GitHub posts when a person installs the app or approves its
+ *  grant — the `aivi add` probe's signal, replayed from the delivery history
+ *  (an older install posts nothing while the installer watches). */
+export const INSTALLATION_EVENTS = new Set(['installation', 'installation_repositories']);
+const describeDelivery = (event, payload) => {
+    const p = (payload ?? {});
+    const number = p.issue?.number;
+    const at = p.repository?.full_name && number !== undefined
+        ? `${p.repository.full_name}#${number}`
+        : 'something the payload did not name';
+    const action = typeof p.action === 'string' ? ` ${p.action}` : '';
+    return `${event}${action} on ${at}`;
+};
+/** Whether the live aivi answers its health endpoint — the same test Linear's
+ *  installer and the CLI make: `GET /health` on the **listen** URL, whatever
+ *  its version. A raw-read config.json can lack the schema defaults, so the
+ *  defaults are filled here: bind 127.0.0.1, port 4100. Pure of prompts, and
+ *  `up` is re-asked on every retry. */
+export async function hostIsUp(fetch, host) {
+    const listen = hostUrl({ bind: host?.bind ?? '127.0.0.1', port: host?.port ?? 4100 });
+    return fetch(`${listen}/health`, { signal: AbortSignal.timeout(2_000) })
+        .then(response => response.ok)
+        .catch(() => false);
+}
+/** The health gate as a choice (ruled 2026-10-07): silence is not a stop, it
+ *  is a fork. Retry re-asks; continue skips the waits and says so — the
+ *  installer still writes its configuration, with UNVERIFIED in the summary. */
+export async function gateHost(prompts, up) {
+    for (;;) {
+        if (await up())
+            return true;
+        const choice = await prompts.select({
+            message: 'No live aivi answers its health endpoint — the probe watches what a running aivi records',
+            options: [
+                { value: 'retry', label: 'I started the server. Retry' },
+                { value: 'skip', label: 'Continue anyway — do not verify the webhook' },
+            ],
+        });
+        if (prompts.isCancel(choice))
+            throw new Error('the setup was cancelled at the health gate');
+        if (choice === 'skip') {
+            await prompts.log.message('Continuing unverified: the configuration is written, but “GitHub can reach this aivi” stays unproved.');
+            return false;
+        }
+    }
+}
+/** The newest diary row id right now. Whatever exists before a test starts is
+ *  nobody's business; anything the test draws lands with a larger id. */
+export const latestId = (store) => {
+    let last = 0;
+    let rows = store.requests({ sinceId: last });
+    while (rows.length) {
+        last = rows[rows.length - 1].id;
+        rows = store.requests({ sinceId: last });
+    }
+    return last;
+};
+/** The seal failure line — same words wherever the seal fails: the secret
+ *  aivi holds is not the secret GitHub sends, and waiting on that changes
+ *  nothing, so every wait ends at once. */
+const badSeal = (row) => new Error(`a delivery arrived but failed the module's own check: bad signature (HTTP ${row.status}).` +
+    ' The secret this aivi holds is not the one GitHub sends — compare <home>/.env with the Secret on the app’s settings page.');
+const verifyRow = (secret, row) => verifyWebhookSignature(secret, Buffer.from(row.body ?? '', 'utf8'), row.headers['x-hub-signature-256'] ?? '');
+/** The seal check every wait runs on every row before anything else. A
+ *  delivery that fails it ends the wait; the payload is the caller's to
+ *  parse. */
+function verifiedRow(secret, row) {
+    if (!verifyRow(secret, row))
+        throw badSeal(row);
+    return JSON.parse(row.body ?? '{}');
+}
+/**
+ * Watch the diary until one verified delivery `accepts` lands, `about` names
+ * the thing under test, or `ms` has passed. A wait that passes is not made to
+ * sit out its window; the window is what a failure needs. Every verified
+ * delivery is said the moment it lands, whatever it names.
+ */
+export async function waitDiary(store, watch, cursor, say) {
+    const { path, secret, windowMs, accepts, about } = watch;
+    let mine = 0;
+    let others = 0;
+    let last = cursor;
+    await new Promise((settledPromise, failed) => {
+        let done = false;
+        let poll;
+        let expiry;
+        const read = () => {
+            // `aivi host clear-logs` can empty the diary and restart its ids below
+            // our cursor; when that happens, follow the fresh diary, not the mark.
+            if (latestId(store) < last)
+                last = 0;
+            for (const row of store.requests({ method: 'POST', path, sinceId: last })) {
+                last = row.id;
+                if (row.truncated)
+                    throw new Error(`a delivery arrived but its body is not readable JSON — the diary cut it off (row ${row.id}) — verification needs the whole body.`);
+                const payload = verifiedRow(secret, row);
+                const event = row.headers['x-github-event'] ?? '';
+                say(`Heard: ${describeDelivery(event, payload)}`); // every delivery, the moment it lands
+                if (!about(event, payload)) {
+                    others++;
+                    continue;
+                }
+                // The proof is in: a passed wait is nobody's waiting room, and the
+                // stop's own read finishes nothing this loop has left to say.
+                if (accepts(event, payload)) {
+                    mine++;
+                    stop();
+                    return;
+                }
+            }
+        };
+        const stop = (error) => {
+            if (done)
+                return;
+            done = true;
+            if (poll !== undefined)
+                clearTimeout(poll);
+            if (expiry !== undefined)
+                clearTimeout(expiry);
+            if (error === undefined) {
+                try {
+                    read(); // the deadline read: complete even if a tick was late
+                }
+                catch (cause) {
+                    failed(cause);
+                    return;
+                }
+                settledPromise();
+            }
+            else
+                failed(error);
+        };
+        const tick = () => {
+            try {
+                read();
+            }
+            catch (cause) {
+                stop(cause);
+                return;
+            }
+            // Self-rescheduling: one pending timer, always, and a slow read
+            // cannot pile up behind itself. And a read that ended the wait is
+            // never re-armed: no timer outlives the verdict.
+            if (done)
+                return;
+            poll = setTimeout(tick, POLL_MS);
+        };
+        poll = setTimeout(tick, POLL_MS); // the reliable arrival signal across processes: a re-read
+        expiry = setTimeout(() => stop(), windowMs); // the window's end: a known instant
+        try {
+            read(); // whatever already arrived before the watching began
+        }
+        catch (cause) {
+            stop(cause);
+        }
+    });
+    return { mine, others, last };
+}
+/** The board probe's five signals: the mutations the wizard pays, and what
+ *  each one's delivery looks like. Names are verdict words; the wizard says
+ *  which landed and which did not. */
+const BOARD_SIGNALS = {
+    'issue opened': (event, payload) => event === 'issues' && payload?.action === 'opened',
+    'card added': (event, payload) => event === 'projects_v2_item' && payload?.action === 'created',
+    'Status moved': (event, payload) => event === 'projects_v2_item' &&
+        payload?.action === 'edited' &&
+        (payload?.changes?.field_name ?? payload?.changes?.field_value?.field_name) === 'Status',
+    'Agent set': (event, payload) => event === 'projects_v2_item' &&
+        payload?.action === 'edited' &&
+        (payload?.changes?.field_name ?? payload?.changes?.field_value?.field_name) === 'Agent',
+    'comment posted': (event, payload) => event === 'issue_comment' && payload?.action === 'created',
+};
+/** Watch for the board probe's signals on one issue until all `asked` have
+ *  landed or the window passes. Each landing is said the moment it arrives —
+ *  the live line names what just came in. A signal already landed is never
+ *  counted twice; the window is what a missing signal needs. */
+export async function waitForSignals(store, watch, cursor, say) {
+    const { path, secret, windowMs, asked, about } = watch;
+    const landed = new Set();
+    let last = cursor;
+    await new Promise((settledPromise, failed) => {
+        let done = false;
+        let poll;
+        let expiry;
+        const read = () => {
+            if (latestId(store) < last)
+                last = 0;
+            const rows = store.requests({ method: 'POST', path, sinceId: last });
+            if (rows.length)
+                last = rows[rows.length - 1].id;
+            // Newest first: the probe's own deliveries are the freshest rows
+            // above the cursor. A truncated row is skipped before parsing — a
+            // cut body cannot be parsed, and its seal could never verify.
+            for (const row of rows.reverse()) {
+                if (row.truncated)
+                    continue;
+                const payload = JSON.parse(row.body ?? '{}');
+                const event = row.headers['x-github-event'] ?? '';
+                if (!about(event, payload))
+                    continue; // about another issue: this test is not about it
+                if (!verifyRow(secret, row))
+                    throw badSeal(row);
+                say(`Heard: ${describeDelivery(event, payload)}`);
+                for (const name of asked) {
+                    if (!landed.has(name) && BOARD_SIGNALS[name](event, payload)) {
+                        landed.add(name);
+                        if (landed.size === asked.length) {
+                            stop();
+                            return;
+                        }
+                    }
+                }
+            }
+        };
+        const stop = (error) => {
+            if (done)
+                return;
+            done = true;
+            if (poll !== undefined)
+                clearTimeout(poll);
+            if (expiry !== undefined)
+                clearTimeout(expiry);
+            if (error === undefined) {
+                try {
+                    read();
+                }
+                catch (cause) {
+                    failed(cause);
+                    return;
+                }
+                settledPromise();
+            }
+            else
+                failed(error);
+        };
+        const tick = () => {
+            try {
+                read();
+            }
+            catch (cause) {
+                stop(cause);
+                return;
+            }
+            if (done)
+                return;
+            poll = setTimeout(tick, POLL_MS);
+        };
+        poll = setTimeout(tick, POLL_MS);
+        expiry = setTimeout(() => stop(), windowMs);
+        try {
+            read();
+        }
+        catch (cause) {
+            stop(cause);
+        }
+    });
+    return { landed, last };
+}
+/** Whether a delivery is about the probe issue. `issue_comment` names it by
+ *  `issue.number`; an `issues` delivery carries its number inside `issue`
+ *  too — GitHub answers no top-level one (the live ledger says so). A
+ *  `projects_v2_item` delivery names neither repo nor number: its payload
+ *  carries no `repository` at all (keys: action, changes, installation,
+ *  organization, projects_v2_item, sender — the live ledger says so), so
+ *  the content's globally unique node id is the whole referee. Requiring a
+ *  repository there filtered every board delivery as foreign and the wait
+ *  sat out its window on signals it already held. */
+export const aboutIssue = (repoId, number, issueNodeId) => (event, payload) => event === 'projects_v2_item'
+    ? payload?.projects_v2_item?.content_node_id === issueNodeId
+    : payload?.repository?.full_name === repoId && payload?.issue?.number === number;
+/** The board probe's verdict, pure: which signals landed, which did not, and
+ *  what the missing one means. A signal never paid for (a board with one open
+ *  Status option cannot show a move) is said as skipped, not as a failure. */
+export function boardProbeVerdict(landed, asked, windowMs) {
+    const missing = asked.filter(name => !landed.has(name));
+    if (!missing.length)
+        return { pass: true, detail: `all ${asked.length} deliveries arrived and verified — every seal matched` };
+    const detail = `${missing.join(', ')} did not arrive in ${windowMs / 1000} s — the events ticked on the app decide what GitHub posts, and GitHub must reach this machine`;
+    return { pass: false, detail };
+}
+/** The remedy line when the health gate's choice was made and the waits were
+ *  skipped: named once, in the summary, in the same words both installers use. */
+export const UNVERIFIED = 'UNVERIFIED — no live aivi watched, so “GitHub can reach this machine” was not proved';

package/dist/projects.d.ts

@@ -0,0 +1,41 @@
+import { type LoadedConfig, type Project, type ProjectLaneInput } from '@aivi/core';
+import type { ProjectGithub } from './config.ts';
+/** The project's GitHub routing as it takes effect: which board speaks for it
+ *  and which repositories feed it. */
+export declare function projectGithub(loaded: LoadedConfig, projectId: string): ProjectGithub | undefined;
+/** A checkout receives one issue stream, so a repository may feed exactly one
+ *  project's board. Said for every collision, not just the first. */
+export declare function githubRepoCollisions(loaded: LoadedConfig): string[];
+/** A project checkout and the GitHub routing that claims issues for it. */
+export interface RoutedProject {
+    project: Project;
+    github: ProjectGithub;
+}
+/** Which aivi project an issue belongs to: by its repository. The board is
+ *  read off the project's own section, so a ticket on a board the project
+ *  does not name is not this project's ticket — that question is the board's
+ *  (`ticketLane`), not the repository's. */
+export declare function projectForIssue(loaded: LoadedConfig, issue: {
+    repo: string;
+}): RoutedProject | undefined;
+/**
+ * Point a project at its board and repositories, and optionally (re)write its
+ * lanes: the section goes to `projects.<id>.tracker-github`, lanes to the
+ * project's **core** `lanes` array — the ordered workflow, which core
+ * validates and the orchestrator decides moves from. Nothing else in the file
+ * is touched; an existing `lanes` stays as it was when none is passed. The
+ * written file must hold: the core config must still load, the section must
+ * parse against this plugin's own schema, and no repository may feed two
+ * projects — if any check fails, the previous bytes are restored and the
+ * error stands.
+ */
+export declare function writeProjectGithub(configPath: string, id: string, options: {
+    board: number;
+    repos: string[];
+    lanes?: ProjectLaneInput[];
+}): Promise<{
+    id: string;
+    board: number;
+    repos: string[];
+    lanes?: ProjectLaneInput[];
+}>;

package/dist/projects.js

@@ -0,0 +1,117 @@
+/** The GitHub tracker's project sections: the write path the `aivi projects`
+ *  wizard uses and the routing the module consults. Repositories are GitHub's
+ *  own; the **lanes are core's** — this file writes them into the project's
+ *  core `lanes` array and reads nothing back from it. One board per project,
+ *  one tracker per project (D1): the orchestrator's registration guard is the
+ *  fatal one; what is checked here is that a repository feeds one board only.
+ */
+import { renameSync, rmSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { loadConfig, PROJECT_ID } from '@aivi/core';
+import { githubProjectSchema } from './config.js';
+/** The module id, which is also the key of this plugin's section under every
+ *  project and under `projectDefaults`. */
+const SECTION = 'tracker-github';
+/** The `tracker-github` section of a project entry as written — typed, or
+ *  undefined. Core passes the section through; reading it is this plugin's
+ *  business. */
+const writtenGithub = (loaded, projectId) => loaded.config.projects[projectId]?.[SECTION];
+/** The `tracker-github` section of `projectDefaults` as written. */
+const writtenDefaults = (loaded) => loaded.config.projectDefaults[SECTION];
+/** The project's GitHub routing as it takes effect: which board speaks for it
+ *  and which repositories feed it. */
+export function projectGithub(loaded, projectId) {
+    const entry = writtenGithub(loaded, projectId);
+    if (!entry)
+        return undefined;
+    const createLane = entry.createLane ?? writtenDefaults(loaded)?.createLane;
+    return { board: entry.board, repos: entry.repos, ...(createLane ? { createLane } : {}) };
+}
+/** A checkout receives one issue stream, so a repository may feed exactly one
+ *  project's board. Said for every collision, not just the first. */
+export function githubRepoCollisions(loaded) {
+    const owners = new Map();
+    const collisions = [];
+    for (const project of Object.keys(loaded.config.projects))
+        for (const repo of writtenGithub(loaded, project)?.repos ?? []) {
+            const owner = owners.get(repo);
+            if (owner && owner !== project)
+                collisions.push(`projects.${project}.${SECTION}.repos: ${repo} already feeds project ${owner}; a repository feeds one board`);
+            owners.set(repo, project);
+        }
+    return collisions;
+}
+/** Which aivi project an issue belongs to: by its repository. The board is
+ *  read off the project's own section, so a ticket on a board the project
+ *  does not name is not this project's ticket — that question is the board's
+ *  (`ticketLane`), not the repository's. */
+export function projectForIssue(loaded, issue) {
+    for (const project of loaded.projects) {
+        if (project.removed)
+            continue;
+        const github = projectGithub(loaded, project.id);
+        if (github?.repos.includes(issue.repo))
+            return { project, github };
+    }
+    return undefined;
+}
+/**
+ * Point a project at its board and repositories, and optionally (re)write its
+ * lanes: the section goes to `projects.<id>.tracker-github`, lanes to the
+ * project's **core** `lanes` array — the ordered workflow, which core
+ * validates and the orchestrator decides moves from. Nothing else in the file
+ * is touched; an existing `lanes` stays as it was when none is passed. The
+ * written file must hold: the core config must still load, the section must
+ * parse against this plugin's own schema, and no repository may feed two
+ * projects — if any check fails, the previous bytes are restored and the
+ * error stands.
+ */
+export async function writeProjectGithub(configPath, id, options) {
+    if (!PROJECT_ID.test(id))
+        throw new Error(`Project id "${id}" must match ${PROJECT_ID}`);
+    if (!options.repos.length)
+        throw new Error('Set at least one repository');
+    const before = await readFile(configPath, 'utf8');
+    const raw = JSON.parse(before);
+    const projects = (raw.projects ?? {});
+    raw.projects = projects;
+    const entry = (projects[id] ?? {});
+    projects[id] = entry;
+    const github = (entry[SECTION] ?? {});
+    entry[SECTION] = github;
+    github.board = options.board;
+    github.repos = options.repos;
+    if (options.lanes)
+        entry.lanes = options.lanes;
+    await writeWhole(configPath, `${JSON.stringify(raw, null, 2)}\n`);
+    try {
+        const loaded = await loadConfig(configPath);
+        githubProjectSchema.parse(github);
+        // A checkout receives one issue stream: the repositories just written may
+        // not feed another project's board too. Collisions between other projects
+        // are not this write's doing; the module's start check says those.
+        const mine = new Set(github.repos);
+        for (const other of Object.keys(loaded.config.projects)) {
+            if (other === id)
+                continue;
+            const shared = (writtenGithub(loaded, other)?.repos ?? []).filter(repo => mine.has(repo));
+            if (shared.length)
+                throw new Error(`Repository ${shared.join(', ')} already feeds project ${other}; a repository feeds one board`);
+        }
+    }
+    catch (error) {
+        await writeWhole(configPath, before);
+        throw error;
+    }
+    const lanes = entry.lanes;
+    return { id, board: options.board, repos: options.repos, ...(lanes ? { lanes } : {}) };
+}
+/** Bytes land whole or not at all: temp next door, rename over the live
+ *  path. The restore-on-refusal pattern protects against a bad write; the
+ *  temp-then-rename protects against a half one. */
+async function writeWhole(path, contents) {
+    const temp = `${path}.aivi-tmp`;
+    rmSync(temp, { force: true });
+    await writeFile(temp, contents);
+    renameSync(temp, path);
+}

package/dist/runprogress.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The worker run's **progress stream**: while a run works, its OpenCode
+ * session is mirrored into the ticket through the platform's transient
+ * progress surface (`Platform.progress`) — GitHub edits the run's status
+ * comment in place, the one line that says what the worker is doing right
+ * now (ruled 2026-10-02: ephemeral by contract — a replaced line must not
+ * linger, and GitHub has no ephemeral activity, so one comment edited is the
+ * honest equivalent). The reducer and the renderer are the host's own
+ * channel machinery, so the worker's line and a chat placeholder say the
+ * same thing in the same words.
+ *
+ * No polling and no interval: besides the throttle's trailing edge, the
+ * only timer waits for the next instant the rendered line changes on its
+ * own (the long-turn suffix, the idle notice, an elapsed refresh). The
+ * follower pauses while a question awaits a person — nothing happens then —
+ * and resumes when the answer lands.
+ */
+import type { Logger } from '@aivi/core';
+import { type ProgressClock } from '@aivi/host';
+import type { SessionEvents } from '@aivi/plugin/module';
+import type { Platform } from '@aivi/plugin/tracker';
+export interface RunProgressOptions {
+    /** `status` shows the one line; `tools` lets a running tool speak in the line. */
+    mode: 'status' | 'tools';
+    events: SessionEvents;
+    log: Logger;
+    /** At most one edit per window: the first at once, later ones coalesced. */
+    throttleMs?: number;
+    clock?: Partial<ProgressClock>;
+}
+export declare class RunProgress {
+    private readonly platform;
+    private readonly conversation;
+    private readonly sessionId;
+    private readonly mode;
+    private readonly events;
+    private readonly log;
+    private readonly throttleMs;
+    private readonly clock;
+    private state;
+    private shown;
+    private lastPostAt;
+    private unwatch;
+    private trailing;
+    private change;
+    private inflight;
+    private following;
+    constructor(platform: Platform, conversation: string, sessionId: string, options: RunProgressOptions);
+    /** Follow the session: watch and arm. Idempotent; a stopped follower
+     *  resumes with its history — the elapsed line keeps counting, because
+     *  the worker did. */
+    start(): void;
+    /** Say nothing more: unwatch, disarm, let the in-flight edit land. */
+    stop(): Promise<void>;
+    /** Wait for the next instant the line changes by itself. */
+    private arm;
+    private schedule;
+    /** One edit per visible change — and only when the text actually
+     *  changed, so the stream says each moment once. A running tool is
+     *  offered as a tool; a `status`-mode follower keeps it inside the line. */
+    private flush;
+}