@aivi/tracker-github 0.0.0-stage → 0.0.0

package/dist/tracker.js

@@ -0,0 +1,505 @@
+/** GitHub's **platform**: the `Platform` contract of `@aivi/plugin/tracker`
+ *  spelled in GitHub's words. It owns everything GitHub-shaped below the
+ *  neutral surface — the one app and its credential (through `@aivi/github`),
+ *  the webhook route and its seal, the board reads and the `Agent` field, the
+ *  status comment and its hidden state (D6, D7) — and translates at the
+ *  border: deliveries become `TrackerEvent`s, neutral updates become GitHub
+ *  mutations. The module's decision code imports **no** GitHub types through
+ *  this file.
+ *
+ *  **Conversations** are the adapter's own affair, and GitHub's are the
+ *  ticket and its status comment (no agent session exists for an app — D5):
+ *
+ *  - `github` — the app's own feed: desk calls and notices, no session.
+ *  - `github:owner/repo#47` — a person brought the ticket: the **assistant's**
+ *    conversation, the ticket itself.
+ *  - `github:owner/repo#47:c123` — a **run's** conversation: the status
+ *    comment `startSession` created (D6). Its body carries the machine state
+ *    as a hidden JSON comment (D7); visible words, plan checklist, and the
+ *    hidden line are all one edited comment.
+ */
+import { getLogger } from '@aivi/core';
+import { verifyWebhookSignature, WEBHOOK_SIGNATURE_HEADER } from '@aivi/github';
+import { MODULE_ID } from './config.js';
+import { projectForIssue, projectGithub } from './projects.js';
+import { DeliveryLedger, editedFieldName, GITHUB_DELIVERY_HEADER, GITHUB_EVENT_HEADER, isBotAuthor, trustedAuthor, } from './webhook.js';
+/** The app's own feed: desk calls and notices speak here — there is no
+ *  session to name, and one app speaks for the home. */
+export const GITHUB_FEED = 'github';
+/** A run conversation's session id: the ticket with its status comment's id
+ *  on it — `owner/repo#47:c123`. */
+const RUN_SESSION = /^(.+#\d+):c(\d+)$/;
+/** A bare ticket ref as a conversation names it: `owner/repo#47`. */
+const TICKET_SESSION = /^([^/]+\/[^#]+)#(\d+)$/;
+/** The hidden machine-state line (D7): JSON in an HTML comment at the body's
+ *  end. GitHub shows a person the words and hands aivi the state. */
+const META_LINE = /<!--\s*(\{[\s\S]*\})\s*-->\s*$/;
+/** Read a status comment's body into its parts. A body with no hidden line
+ *  (a person edited it away) still reads: the state defaults to a standing
+ *  status, and the words are whatever stands. */
+export function parseStatus(body) {
+    const found = META_LINE.exec(body);
+    let meta = { kind: 'status' };
+    let rest = body;
+    if (found) {
+        try {
+            meta = JSON.parse(found[1]);
+        }
+        catch {
+            /* a person broke the JSON: the state is unreadable, the status stands */
+        }
+        rest = body.slice(0, found.index).trimEnd();
+    }
+    const lines = rest.split('\n');
+    const head = lines.shift() ?? '';
+    const planLines = [];
+    const at = lines.indexOf('### Plan');
+    if (at >= 0)
+        for (const line of lines.slice(at + 1))
+            if (line.startsWith('- '))
+                planLines.push(line);
+    return { head, planLines, meta };
+}
+/** The whole body from its parts: head line, plan section when there is
+ *  one, and the hidden line last. */
+export function renderStatus(head, planLines, meta) {
+    const parts = [head];
+    if (planLines.length)
+        parts.push(['### Plan', ...planLines].join('\n'));
+    parts.push(`<!-- ${JSON.stringify(meta)} -->`);
+    return `${parts.join('\n\n')}\n`;
+}
+const planStepLine = (step) => step.status === 'completed'
+    ? `- [x] ${step.content}`
+    : step.status === 'canceled'
+        ? `- [-] ${step.content}`
+        : `- [ ] ${step.content}`;
+/** The error a read answers when the surface it read is gone: shaped so
+ *  `isGoneError` says gone, because the closer's drop-the-debt path keys on
+ *  it exactly as Linear's does on `Entity not found`. */
+const gone = (what) => {
+    const error = new Error(`${what} is gone (deleted, or never visible to the app)`);
+    error.status = 404;
+    return error;
+};
+export class GithubPlatform {
+    id = MODULE_ID;
+    loaded;
+    client;
+    webhookSecret;
+    log;
+    deliveries = new DeliveryLedger();
+    sinks = new Set();
+    /** The divider line for comments (ruled 2026-10-07): who GitHub says may
+     *  talk. Read per delivery from `author_association`; an untrusted comment
+     *  is nothing — no event, no reply, no log line. */
+    trust;
+    /** Which board node ids aivi speaks, by board number — warmed at start.
+     *  A `projects_v2_item` delivery names its board by node id and nothing
+     *  else; a board nobody configured is noise and says nothing. */
+    boardNodes = new Map();
+    constructor(loaded, client, webhookSecret, log = getLogger(['aivi', MODULE_ID]), trust = 'members') {
+        this.loaded = loaded;
+        this.client = client;
+        this.webhookSecret = webhookSecret;
+        this.log = log;
+        this.trust = trust;
+    }
+    /** Resolve every configured board's fields once, at module start: it says
+     *  of a missing `Status` or `Agent` field before any walk asks, and it
+     *  teaches the delivery filter which boards are ours. */
+    async warm() {
+        for (const project of this.loaded.projects) {
+            if (project.removed)
+                continue;
+            const github = projectGithub(this.loaded, project.id);
+            if (!github)
+                continue;
+            const fields = await this.client.boardFields(github.board);
+            this.boardNodes.set(fields.projectId, github.board);
+        }
+    }
+    // ——— board lookups ———
+    /** Which board speaks for a repository's issues, and for a ticket by way
+     *  of its repository. */
+    boardOfRepo(repo) {
+        return projectForIssue(this.loaded, { repo: repo })?.github;
+    }
+    boardOf(issueId) {
+        const repo = issueId.slice(0, issueId.indexOf('#'));
+        const github = this.boardOfRepo(repo);
+        if (!github)
+            throw new Error(`${issueId} feeds no aivi project: ${repo} is in no project's repos`);
+        return github;
+    }
+    // ——— the neutral surface ———
+    async laneStates(_conversation, teamId) {
+        const github = this.boardOfRepo(teamId);
+        if (!github)
+            throw new Error(`${teamId} feeds no aivi project: it has no board and no states`);
+        return (await this.client.laneOptions(github.board)).map(o => ({ id: o.id, name: o.name, type: '' }));
+    }
+    /** `createStates` is deliberately absent (D4): lanes map onto the board's
+     *  own Status options, and aivi never creates or renames one — the human's
+     *  board is not aivi's to edit. */
+    async apply(_conversation, issueId, update) {
+        if (update.kind === 'move') {
+            await this.client.setLane(issueId, this.boardOf(issueId).board, update.lane);
+            return;
+        }
+        if (update.kind === 'label') {
+            if (update.on)
+                await this.client.addLabel(issueId, update.label);
+            else
+                await this.client.removeLabel(issueId, update.label);
+            return;
+        }
+        await this.client.createComment(issueId, update.text);
+    }
+    async issue(_conversation, issueId) {
+        return this.neutralIssue(await this.client.issue(issueId));
+    }
+    async assign(_conversation, issueId, userId) {
+        await this.client.setAgent(issueId, this.boardOf(issueId).board, userId);
+    }
+    async unassign(_conversation, issueId) {
+        await this.client.setAgent(issueId, this.boardOf(issueId).board, null);
+    }
+    /** Open the run's conversation (D6): one status comment, the first word
+     *  visible and the machine state hidden under it. Its id, with the ticket
+     *  on it, is the conversation handle the module records. */
+    async startSession(_conversation, issueId) {
+        const made = await this.client.createComment(issueId, renderStatus('**Preparing the workspace…**', [], { kind: 'status' }));
+        return `${issueId}:c${made.id}`;
+    }
+    idFor(sessionId) {
+        return `${GITHUB_FEED}:${sessionId}`;
+    }
+    parts(conversation) {
+        if (conversation === GITHUB_FEED)
+            return { app: GITHUB_FEED, session: '' };
+        const session = conversation.startsWith(`${GITHUB_FEED}:`)
+            ? conversation.slice(GITHUB_FEED.length + 1)
+            : conversation;
+        return { app: GITHUB_FEED, session };
+    }
+    async orgOf(_conversation) {
+        return this.client.org;
+    }
+    /** Who aivi is on a ticket: the `Agent` field's option named for the app
+     *  (D5) — the same word on every board; per-board option ids are the
+     *  client's resolution detail. */
+    ownerOf(_conversation) {
+        return this.client.delegateName;
+    }
+    /** One message into a conversation, and the conversation decides what a
+     *  transient word **is**: inside a run it edits the status comment (no
+     *  second comment may linger — transient by contract); on a ticket it is
+     *  the assistant's placeholder, a real comment the engine may edit by id
+     *  and delete when the answer lands. */
+    async comment(conversation, text, kind) {
+        const session = this.parts(conversation).session;
+        const run = RUN_SESSION.exec(session);
+        if (run) {
+            if (kind === 'progress') {
+                await this.progress(conversation, { text });
+                return undefined;
+            }
+            const made = await this.client.createComment(run[1], text);
+            return String(made.id);
+        }
+        if (!TICKET_SESSION.test(session))
+            throw new Error(`${conversation} is not a conversation a comment lands on`);
+        const made = await this.client.createComment(session, text);
+        return String(made.id);
+    }
+    /** Replace the status comment's line — the only edit a progress word may
+     *  make. A frozen comment (the closing landed) is left as it stands: the
+     *  closing is the last word, and a trailing in-flight edit never speaks
+     *  after it. */
+    async progress(conversation, line) {
+        const { ref, commentId } = this.runOf(conversation);
+        const body = await this.client.getComment(ref, commentId);
+        if (body === undefined)
+            throw gone(`the status comment of ${ref}`);
+        const standing = parseStatus(body);
+        if (standing.meta.kind === 'done')
+            return;
+        const tool = line.tool ? ` · \`${line.tool.name}${line.tool.detail ? ` ${line.tool.detail}` : ''}\`` : '';
+        await this.client.updateComment(ref, commentId, renderStatus(`**${line.text}**${tool}`, standing.planLines, standing.meta));
+    }
+    /** A run that died before it had a conversation still speaks on the
+     *  ticket: silence is not an answer (ruled 2026-10-02). */
+    async notify(_conversation, issueId, text) {
+        await this.client.createComment(issueId, text);
+    }
+    /** Has this run's result been rendered? GitHub keeps no session to ask:
+     *  the answer is a comment on the ticket whose hidden line says
+     *  `kind: closing` **and names this run's status comment** — so a catch-up
+     *  says each run's result once, and a second run on the same ticket is a
+     *  different conversation with its own result. */
+    async resultShown(conversation) {
+        const { ref, commentId } = this.runOf(conversation);
+        for (const comment of await this.client.comments(ref)) {
+            if (!isBotAuthor({ type: comment.authorIsBot ? 'Bot' : 'User' }))
+                continue;
+            const meta = parseStatus(comment.body).meta;
+            if (meta.kind === 'closing' && Number(meta.status) === commentId)
+                return true;
+        }
+        return false;
+    }
+    /** Put the worker's question to the people (required of every tracker):
+     *  GitHub Issues renders a numbered comment; the answer arrives as an
+     *  ordinary comment and the open OpenCode form tells it from chatter. */
+    async ask(conversation, question) {
+        const { ref } = this.runOf(conversation);
+        const lines = [`**Question** · ${question.question}`];
+        if (question.options?.length)
+            lines.push(question.options
+                .map((o, i) => `${i + 1}. ${o.label}${o.value === o.label ? '' : ` — \`${o.value}\``}`)
+                .join('\n'));
+        await this.client.createComment(ref, renderStatus(lines.join('\n\n'), [], { kind: 'question' }));
+    }
+    /** Show the worker's plan: the whole checklist, replacing what stood, in
+     *  the status comment's own plan section. */
+    async plan(conversation, plan) {
+        const { ref, commentId } = this.runOf(conversation);
+        const body = await this.client.getComment(ref, commentId);
+        if (body === undefined)
+            throw gone(`the status comment of ${ref}`);
+        const standing = parseStatus(body);
+        await this.client.updateComment(ref, commentId, renderStatus(standing.head, plan.steps.map(planStepLine), standing.meta));
+    }
+    // ——— the ticket desk (the app's own feed; conversation selects nothing) ———
+    async ticketComments(_conversation, issueId) {
+        return this.client.comments(issueId);
+    }
+    async addComment(_conversation, issueId, text) {
+        await this.client.createComment(issueId, text);
+    }
+    async editIssue(_conversation, issueId, changes) {
+        return this.neutralIssue(await this.client.updateIssue(issueId, changes));
+    }
+    async createIssue(_conversation, input) {
+        const { lane, ...words } = input;
+        const made = await this.client.createIssue(input.teamId, {
+            title: words.title,
+            ...(words.description !== undefined ? { body: words.description } : {}),
+        });
+        if (lane) {
+            const board = this.boardOfRepo(input.teamId)?.board;
+            if (board === undefined)
+                throw new Error(`${input.teamId} feeds no aivi project: ${lane} is nowhere to land it`);
+            const options = await this.client.laneOptions(board);
+            if (!options.some(o => o.name === lane))
+                throw new Error(`board ${board} of ${this.client.org} has no Status option "${lane}": it exists on the board or aivi will not guess past it`);
+            await this.client.setLane(made.ref, board, lane);
+        }
+        return this.neutralIssue(made);
+    }
+    async teamLabels(_conversation, teamId) {
+        return this.client.repoLabels(teamId);
+    }
+    events(sink) {
+        this.sinks.add(sink);
+        return () => this.sinks.delete(sink);
+    }
+    // ——— the closing's own words (the module's, not the contract's) ———
+    /** The run's final word: a comment of its own, tied to its status comment
+     *  so `resultShown` can swear each run said its result once. */
+    async markClosing(conversation, text, success) {
+        const { ref, commentId } = this.runOf(conversation);
+        await this.client.createComment(ref, renderStatus(text, [], { kind: 'closing', status: commentId, ok: success }));
+    }
+    /** Freeze the status comment: the working line goes, the terminal word
+     *  stands. Idempotent — a retry lands on an already-frozen comment as
+     *  nothing. */
+    async freezeStatus(conversation, head) {
+        const { ref, commentId } = this.runOf(conversation);
+        const body = await this.client.getComment(ref, commentId);
+        if (body === undefined)
+            throw gone(`the status comment of ${ref}`);
+        const standing = parseStatus(body);
+        if (standing.meta.kind === 'done')
+            return;
+        await this.client.updateComment(ref, commentId, renderStatus(head, standing.planLines, { ...standing.meta, kind: 'done' }));
+    }
+    // ——— inbound: the whole delivery surface ———
+    /** One delivery, whole: the seal first (bytes, not re-serialized JSON),
+     *  the redelivery filter second, then the acknowledgement — GitHub retries
+     *  anything but a 200, and a handler that fails later must not invite a
+     *  replay of what already ran. */
+    async deliver(request) {
+        const event = request.headers[GITHUB_EVENT_HEADER];
+        const delivery = request.headers[GITHUB_DELIVERY_HEADER];
+        const signature = request.headers[WEBHOOK_SIGNATURE_HEADER];
+        if (!event)
+            return { status: 400, body: { error: 'missing X-GitHub-Event' } };
+        if (!delivery)
+            return { status: 400, body: { error: 'missing X-GitHub-Delivery' } };
+        if (!signature || !verifyWebhookSignature(this.webhookSecret, request.body, signature)) {
+            this.log.warn('webhook.refused', { delivery, reason: 'signature mismatch' });
+            return { status: 401, body: { error: 'signature mismatch' } };
+        }
+        if (!this.deliveries.fresh(delivery))
+            return { status: 200, body: { ok: true, duplicate: true } };
+        let payload;
+        try {
+            payload = JSON.parse(request.body.toString('utf8'));
+        }
+        catch {
+            return { status: 400, body: { error: 'body is not JSON' } };
+        }
+        this.dispatch(event, payload).catch(error => {
+            this.log.warn('webhook.failed', { delivery, event, error });
+        });
+        return { status: 200, body: { ok: true } };
+    }
+    /** Translate one delivery into normalized events — or into nothing.
+     *  `ping`, `installation`, board reorderings, bot comments (aivi answering
+     *  itself), and every action outside the routing set are noise (live,
+     *  2026-10-07). */
+    async dispatch(event, payload) {
+        if (event === 'issue_comment') {
+            const p = payload;
+            if (p.action !== 'created' || isBotAuthor(p.comment?.user) || p.issue?.number === undefined)
+                return;
+            // The divider line (ruled 2026-10-07): on a public repository anyone may
+            // comment, but only a trusted author reaches a worker or the assistant.
+            // An untrusted one is dropped here — the one gate for all three paths
+            // (form answer, steer, assistant) — with no reply (silence does not
+            // advertise the bot) and no log line (drive-by comments are a public
+            // repo's weather). A lane or label move needs board write access GitHub
+            // itself enforces, so the other two events need no gate.
+            if (!trustedAuthor(p.comment?.author_association, this.trust))
+                return;
+            await this.emit({
+                kind: 'prompted',
+                id: `comment:${p.comment.id}`,
+                conversation: this.idFor(`${p.repository.full_name}#${p.issue.number}`),
+                ...(p.comment.body === null ? {} : { body: p.comment.body }),
+            });
+            return;
+        }
+        if (event === 'issues') {
+            const p = payload;
+            // The number is inside `issue` — a top-level one is undefined, and an
+            // id built from undefined is the failure the live ledger caught.
+            if (p.issue?.number === undefined)
+                return;
+            const changed = issueChanges(p.action);
+            if (!changed.length)
+                return;
+            await this.emit({
+                kind: 'updated',
+                conversation: GITHUB_FEED,
+                issueId: `${p.repository.full_name}#${p.issue.number}`,
+                changed,
+            });
+            return;
+        }
+        if (event === 'projects_v2_item') {
+            const p = payload;
+            const item = p.projects_v2_item;
+            if (!item)
+                return;
+            const boardNumber = this.boardNodes.get(item.project_node_id);
+            if (boardNumber === undefined)
+                return; // a board aivi does not speak
+            let changed;
+            if (p.action === 'created')
+                changed = ['state']; // added to the board: the walk should look
+            else if (p.action === 'edited') {
+                const field = editedFieldName(p.changes);
+                if (field === undefined)
+                    return;
+                changed = field === 'Status' ? ['state'] : field === 'Agent' ? ['delegate'] : [];
+            }
+            else
+                return; // reordered, archived, moved: noise or nothing routing keys on
+            if (!changed.length)
+                return;
+            const nodeId = item.content_node_id;
+            if (!nodeId)
+                return;
+            const ref = await this.client.nodeRef(nodeId);
+            if (!ref)
+                return; // a draft or a pull request: not a ticket
+            await this.emit({ kind: 'updated', conversation: GITHUB_FEED, issueId: ref, changed });
+            return;
+        }
+        // ping, installation, repository events and everything else: nothing.
+    }
+    async emit(event) {
+        for (const sink of this.sinks)
+            await sink(event);
+    }
+    // ——— mapping ———
+    /** A GitHub issue in neutral words. The lane is the ticket's Status on the
+     *  board its repository feeds; a repository outside every project has no
+     *  lane and no delegate, and routing says so rather than inventing one. */
+    neutralIssue(issue) {
+        const board = this.boardOfRepo(issue.repo)?.board;
+        const lane = board === undefined ? undefined : this.client.laneOf(issue, board);
+        const agent = board === undefined ? undefined : this.client.agentOn(issue, board);
+        return {
+            id: issue.ref,
+            identifier: issue.ref,
+            title: issue.title,
+            description: issue.body,
+            // GitHub names no branch for a ticket; the tracker generates one (D8).
+            branchName: '',
+            url: issue.url,
+            state: { id: lane?.optionId ?? '', name: lane?.name ?? '', type: '' },
+            teamId: issue.repo,
+            labels: issue.labels,
+            delegateId: agent ?? null,
+            assignee: issue.assignees[0] ? { id: issue.assignees[0].id, name: issue.assignees[0].name } : null,
+            // GitHub never deletes an issue; a `deleted` delivery says so by the
+            // ticket answering nothing, and that is `gone`'s path.
+            archived: false,
+            completed: issue.state === 'closed',
+            blockedBy: issue.blockedBy,
+        };
+    }
+    /** The ticket and status-comment id behind a run conversation, or the
+     *  plain error that this conversation is not one. */
+    runOf(conversation) {
+        const session = this.parts(conversation).session;
+        const found = RUN_SESSION.exec(session);
+        if (!found)
+            throw new Error(`${conversation} is not a run conversation (github:<owner>/<repo>#<n>:<comment id>)`);
+        return { ref: found[1], commentId: Number(found[2]) };
+    }
+    /** A ticket conversation's ref, if the conversation is one. */
+    ticketOf(conversation) {
+        const session = this.parts(conversation).session;
+        return TICKET_SESSION.test(session) ? session : undefined;
+    }
+}
+/** The neutral changes an `issues` action carries, or none. `assigned` and
+ *  `unassigned` are **assignees** — a person's word on GitHub, not the
+ *  delegate, which lives in the board's `Agent` field (D5). */
+export function issueChanges(action) {
+    if (action === 'labeled' || action === 'unlabeled')
+        return ['labels'];
+    if (action === 'closed' || action === 'reopened')
+        return ['state'];
+    if (action === 'deleted')
+        return ['archive'];
+    return [];
+}
+/** The public route GitHub is pointed at — no `/app` tail: the seal and the
+ *  one app make a second path meaningless. */
+export const GITHUB_WEBHOOK_PATH = '/github/webhooks';
+/** Own the route; the platform owns the seal, the dedupe and the words.
+ *  Failures after the acknowledgement never ride the status: a retry would
+ *  only replay what already ran. */
+export function registerWebhookRoute(routes, platform, _log = getLogger(['aivi', MODULE_ID])) {
+    return routes.register(GITHUB_WEBHOOK_PATH, async (request) => {
+        if (request.method !== 'POST')
+            return { status: 405, body: { error: 'Use POST' } };
+        return platform.deliver(request);
+    });
+}

package/dist/webhook.d.ts

@@ -0,0 +1,102 @@
+/** The parts of GitHub's delivery payloads the tracker reads — all of it
+ *  **untrusted input**, parsed only after the seal verified. GitHub names the
+ *  event in the `X-GitHub-Event` header, not in the body, and deduplicates
+ *  redeliveries by `X-GitHub-Delivery`: the same id may arrive twice, and the
+ *  second must land as nothing.
+ *
+ *  What deliberately is **not** read: `ping` (the settings page's hello),
+ *  `installation` events (noise on permission changes, live 2026-10-07),
+ *  `projects_v2_item` `reordered` (one per board drag, no routing meaning),
+ *  and `issues.assigned` — an **assignee** is a person's label on GitHub;
+ *  the delegate lives in the board's `Agent` field (D5).
+ */
+/** The delivery headers every GitHub webhook carries. Delivery ids exceed
+ *  2^53 (live, 2026-10-07) — they are strings here and nowhere a number. */
+export interface GithubDeliveryHeaders {
+    event: string | undefined;
+    delivery: string | undefined;
+    signature: string | undefined;
+}
+export declare const GITHUB_EVENT_HEADER = "x-github-event";
+export declare const GITHUB_DELIVERY_HEADER = "x-github-delivery";
+/** Who comments may reach aivi (ruled 2026-10-07): `members` is the divider
+ *  line for a public repository — GitHub's own association words decide it,
+ *  read per delivery so a promotion or a removal takes effect at once.
+ *  `everyone` opens the door to any GitHub user. */
+export type GithubTrust = 'members' | 'everyone';
+export declare const trustedAuthor: (association: string | undefined, trust: GithubTrust) => boolean;
+/** The comment author as GitHub answers it: `Bot` is an app, and aivi's own
+ *  posts — the status comment, closings, questions — are how a run speaks.
+ *  Inbound, every `Bot` post is filtered: aivi never answers itself. */
+export declare const isBotAuthor: (user: {
+    type?: string | null;
+} | undefined | null) => boolean;
+/** An `issue_comment` delivery: a person's message inside a ticket. */
+export interface IssueCommentPayload {
+    action: string;
+    comment: {
+        id: number;
+        body: string | null;
+        user: {
+            login: string;
+            type?: string;
+        } | null;
+        author_association?: string;
+    };
+    issue: {
+        number: number;
+    };
+    repository: {
+        full_name: string;
+    };
+}
+/** An `issues` delivery: the ticket itself changed. The number lives inside
+ *  `issue` — GitHub answers no top-level one (the live ledger says so). */
+export interface IssuesPayload {
+    action: string;
+    issue?: {
+        number: number;
+    };
+    label?: {
+        name: string;
+    };
+    repository: {
+        full_name: string;
+    };
+}
+/** A `projects_v2_item` delivery: the board moved the ticket or changed a
+ *  field on it. Both ids ride inside `projects_v2_item`: the board names
+ *  itself by `project_node_id`, the ticket by flat `content_node_id` —
+ *  GitHub posts no top-level board id and no nested content object (the
+ *  live ledger says so). The ref behind the node id is one lookup away
+ *  (`client.nodeRef`). */
+export interface ProjectsV2ItemPayload {
+    action: string;
+    changes?: {
+        field_name?: string;
+        field_value?: {
+            from?: string;
+            to?: string;
+            field_name?: string;
+        };
+    };
+    projects_v2_item: {
+        project_node_id: string;
+        content_node_id: string | null;
+    } | null;
+}
+/** The field a `projects_v2_item` edit changed, however GitHub spelled the
+ *  delivery that day: `changes.field_name` per the docs, and the probe
+ *  (live, 2026-10-07) saw it under `changes.field_value.field_name` too.
+ *  Both readings, or a silent miss on every lane move. */
+export declare const editedFieldName: (changes: ProjectsV2ItemPayload['changes']) => string | undefined;
+/** Redeliveries by delivery id, bounded. GitHub resends the same id when a
+ *  reply was lost; the second sight must not run the handler twice. Oldest
+ *  falls out first — a window of a thousand deliveries is days of traffic. */
+export declare class DeliveryLedger {
+    private readonly seen;
+    private readonly capacity;
+    constructor(capacity?: number);
+    /** True the **first** time an id is named; every later sight says nothing. */
+    fresh(delivery: string): boolean;
+}

package/dist/webhook.js

@@ -0,0 +1,52 @@
+/** The parts of GitHub's delivery payloads the tracker reads — all of it
+ *  **untrusted input**, parsed only after the seal verified. GitHub names the
+ *  event in the `X-GitHub-Event` header, not in the body, and deduplicates
+ *  redeliveries by `X-GitHub-Delivery`: the same id may arrive twice, and the
+ *  second must land as nothing.
+ *
+ *  What deliberately is **not** read: `ping` (the settings page's hello),
+ *  `installation` events (noise on permission changes, live 2026-10-07),
+ *  `projects_v2_item` `reordered` (one per board drag, no routing meaning),
+ *  and `issues.assigned` — an **assignee** is a person's label on GitHub;
+ *  the delegate lives in the board's `Agent` field (D5).
+ */
+export const GITHUB_EVENT_HEADER = 'x-github-event';
+export const GITHUB_DELIVERY_HEADER = 'x-github-delivery';
+/** GitHub's words for who the author is to the repository: OWNER (the org
+ *  itself), MEMBER (invited to the org) and COLLABORATOR (outside, with
+ *  repository access) may talk to aivi. CONTRIBUTOR — merely someone with a
+ *  merged pull request — does not buy free access (ruled 2026-10-07), and
+ *  neither does NONE. A missing association fails closed: GitHub always
+ *  sends it, so its absence is a payload aivi does not know. */
+const MEMBER_ASSOCIATIONS = new Set(['OWNER', 'MEMBER', 'COLLABORATOR']);
+export const trustedAuthor = (association, trust) => trust === 'everyone' || (association !== undefined && MEMBER_ASSOCIATIONS.has(association));
+/** The comment author as GitHub answers it: `Bot` is an app, and aivi's own
+ *  posts — the status comment, closings, questions — are how a run speaks.
+ *  Inbound, every `Bot` post is filtered: aivi never answers itself. */
+export const isBotAuthor = (user) => user?.type === 'Bot';
+/** The field a `projects_v2_item` edit changed, however GitHub spelled the
+ *  delivery that day: `changes.field_name` per the docs, and the probe
+ *  (live, 2026-10-07) saw it under `changes.field_value.field_name` too.
+ *  Both readings, or a silent miss on every lane move. */
+export const editedFieldName = (changes) => changes?.field_name ?? changes?.field_value?.field_name;
+/** Redeliveries by delivery id, bounded. GitHub resends the same id when a
+ *  reply was lost; the second sight must not run the handler twice. Oldest
+ *  falls out first — a window of a thousand deliveries is days of traffic. */
+export class DeliveryLedger {
+    seen = new Set();
+    capacity;
+    constructor(capacity = 1024) {
+        this.capacity = capacity;
+    }
+    /** True the **first** time an id is named; every later sight says nothing. */
+    fresh(delivery) {
+        if (this.seen.has(delivery))
+            return false;
+        this.seen.add(delivery);
+        if (this.seen.size > this.capacity) {
+            const oldest = this.seen.values().next().value;
+            this.seen.delete(oldest);
+        }
+        return true;
+    }
+}