@aivi/forge-github 0.0.0-stage → 0.0.0

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @aivi/forge-github
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The GitHub forge: the remote a project came from, the pull requests over its
+branches, and the review conversation on them. aivi speaks as **its own app** —
+one installation, one token octokit owns the whole life of — never as the
+person at the keyboard.
+
+## Exports
+
+| Path | Contents |
+| --- | --- |
+| `@aivi/forge-github` | `GitHubApp`, `createGitHubForge`, `createForgeGithubModule` |
+| `@aivi/forge-github/config` | the registry declaration: module id and `plugins.forge-github` schema |
+| `@aivi/forge-github/setup` | the guide `aivi add` runs |
+| `@aivi/forge-github/setupProject` | the `forge`-role contributor `aivi projects add` runs |
+
+## Model
+
+- **Remote is the line.** Anything that reaches `origin` authenticates and so
+  belongs here: clone, fetch, the `source/` sync, push. Worktrees and commits
+  stay with whoever works locally, and this package never performs them.
+- **One installation and only one.** An installation is the grant from an
+  account to the app; zero or several is a setup error naming what to fix,
+  never a mode.
+- **The credential goes in the command's own environment**, and the URL is
+  named on the command line rather than read from the checkout: a token is left
+  in no file, and the person's stored credential is never offered.
+- **Every post names its worker**, in the text a person reads — so the review
+  a wake is handed can tell aivi's own comments from a human's replies.
+
+## Status
+
+The contract, the credential and the transfers are built and tested against a
+scripted GitHub and a real local repository. Nothing asks a forge a question
+yet: the host-side forge registry — the first thing with "who owns this
+project's remote?" to ask — arrives with the orchestrator.
+
+## Dependencies
+
+`octokit` and `@octokit/auth-app`; `@aivi/host` as a peer (the module runs
+in-process with the host).
+
+## Docs
+
+[plan (the contract, the boundary, what is left)](../../docs/plans/forge-github.md)

package/dist/config.d.ts

@@ -0,0 +1,35 @@
+/** The GitHub forge's registry declaration, at its `./config` subpath: the
+ *  module id and the block's own schema. The CLI imports this for every
+ *  command, so nothing here pulls octokit — `createModule` reaches the module
+ *  code lazily.
+ *
+ *  **The block holds nothing** (ruled 2026-10-07): the app's identity moved to
+ *  the environment — `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` in
+ *  `<home>/.env` — because the forge and the tracker are one app and a plugin
+ *  block cannot be the shared source for two plugins (`@aivi/github` reads
+ *  both). The repositories come from each project's own `origin`; there is no
+ *  per-project forge config. The empty block still marks the forge as
+ *  configured: core offers the forge role to a project only when its block
+ *  stands in `config.json`.
+ */
+import type { AiviPlugin } from '@aivi/plugin';
+import { z } from 'zod';
+/**
+ * The `forge-github` module: the repository host a project's `origin` names,
+ * the pull requests over its branches, and the review conversation on them.
+ * It speaks as **its own app** — an installation token, minted and renewed by
+ * octokit — never as a human's credentials, exactly as the Linear app does.
+ * One installation and only one: the app grants aivi access to a repository
+ * set through it, and aivi has no vocabulary for more than one.
+ *
+ * The block lives at `plugins.forge-github` in config.json; the `aivi-plugins`
+ * list in `app/package.json` says whether the module runs.
+ */
+export declare const forgeGithubSchema: z.ZodObject<{}, z.core.$strict>;
+export type ForgeGithubConfig = z.infer<typeof forgeGithubSchema>;
+/** The registry entry: the block holds no paths, so `home` finds nothing to
+ *  resolve here. No project section is contributed: which repository a project
+ *  works is a fact about its checkout, not about its configuration. The block
+ *  itself is unused by the module — the credential is read from the
+ *  environment where it is written. */
+export declare const plugin: AiviPlugin<ForgeGithubConfig>;

package/dist/config.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+/**
+ * The `forge-github` module: the repository host a project's `origin` names,
+ * the pull requests over its branches, and the review conversation on them.
+ * It speaks as **its own app** — an installation token, minted and renewed by
+ * octokit — never as a human's credentials, exactly as the Linear app does.
+ * One installation and only one: the app grants aivi access to a repository
+ * set through it, and aivi has no vocabulary for more than one.
+ *
+ * The block lives at `plugins.forge-github` in config.json; the `aivi-plugins`
+ * list in `app/package.json` says whether the module runs.
+ */
+export const forgeGithubSchema = z.strictObject({});
+/** The registry entry: the block holds no paths, so `home` finds nothing to
+ *  resolve here. No project section is contributed: which repository a project
+ *  works is a fact about its checkout, not about its configuration. The block
+ *  itself is unused by the module — the credential is read from the
+ *  environment where it is written. */
+export const plugin = {
+    id: 'forge-github',
+    configSchema: forgeGithubSchema,
+    // The lazy load is the design: the CLI reads this file's schema without
+    // pulling the host's world in, and the module arrives only when the host
+    // actually builds. The cycle back into this file (the module imports its
+    // own schema) is that design, not a tangle.
+    createModule: () => import('./module.js').then(m => m.createForgeGithubModule()),
+};

package/dist/forge.d.ts

@@ -0,0 +1,117 @@
+import { type Logger } from '@aivi/core';
+import { type GitHubApp, type GitRunner } from '@aivi/github';
+import type { Forge, ForgeProject, ForgeSync, PrFacts, RepoRef, ReviewFacts } from '@aivi/plugin/forge';
+export declare class GitHubForge implements Forge {
+    readonly app: GitHubApp;
+    private readonly log;
+    private readonly git;
+    constructor(app: GitHubApp, options?: {
+        log?: Logger;
+        git?: GitRunner;
+    });
+    /** The checkout's own `origin`, read locally: a project aivi has never
+     *  cloned is not less a project for it. Anything that is not a GitHub
+     *  repository — another host, a local path, no remote at all — is answered
+     *  with silence, because the answer belongs to another forge or to nobody. */
+    repoFor(project: ForgeProject): Promise<RepoRef | undefined>;
+    /** The newest pull request over the branch: a branch whose first attempt was
+     *  closed and reopened has a live one and a dead one, and aivi means the
+     *  live one. */
+    prForBranch(repo: RepoRef, branch: string): Promise<PrFacts | undefined>;
+    /** Everything a review wake needs, in one read: the state of the approvals,
+     *  the threads still open, and the plain conversation comments — context
+     *  the worker reads but is never gated on. A pull request aivi cannot see
+     *  is said, not answered empty — an empty review sends a worker away
+     *  believing it is done. And a read that could not hold everything is
+     *  **said too**: `hasNextPage` on either connection is a
+     *  loud `review.facts.truncated`, the same word Linear keeps for its own
+     *  wide board reads — silence here leaves a worker owing answers it
+     *  believed were gathered. */
+    reviewFeedback(repo: RepoRef, pr: PrFacts): Promise<ReviewFacts>;
+    /** Answer the thread as aivi, then resolve it: the worker's words, signed
+     *  with the role that wrote them, closing the person's question. */
+    resolveThread(repo: RepoRef, _pr: PrFacts, threadId: string, reply: {
+        author: string;
+        text: string;
+    }): Promise<void>;
+    /** A plain conversation comment, signed like every aivi post: what the
+     *  worker says when there is no thread to answer. */
+    commentPr(repo: RepoRef, pr: PrFacts, comment: {
+        author: string;
+        text: string;
+    }): Promise<void>;
+    /** The review agent's teeth: findings on the lines themselves, which the
+     *  platform shows as review threads — agent feedback that the next round's
+     *  worker owes answers on. Every inline body carries the signature like
+     *  every aivi post, so a wake can tell its own findings from a human's. */
+    submitReview(repo: RepoRef, pr: PrFacts, review: {
+        author: string;
+        body: string;
+        state: 'COMMENT' | 'REQUEST_CHANGES';
+        comments?: {
+            path: string;
+            line?: number;
+            body: string;
+        }[];
+    }): Promise<void>;
+    /** The URL and credential for one transfer. The URL is the one this forge
+     *  named when it claimed the project — HTTPS, whatever the checkout's own
+     *  `origin` says, because an installation token authenticates HTTPS and
+     *  nothing else — and it is used as given: re-reading it here would let a
+     *  checkout's config decide where aivi's credential is sent. */
+    private transfer;
+    /**
+     * Fetch, then fast-forward — and stop at that. Every case that would need a
+     * decision is reported with its reason: `source/` is the clean checkout
+     * aivi indexes, not a working directory, so aivi never merges a conflict,
+     * never discards a person's edit, and never rewrites history.
+     *
+     * The fetch names its refspec instead of trusting `origin`'s: the URL aivi
+     * authenticates is HTTPS, which for an ssh checkout is not the URL
+     * configured, and a fetch by URL updates only what its refspec names.
+     */
+    syncSource(repo: RepoRef, directory: string): Promise<ForgeSync>;
+    /**
+     * The one fetch the worktree machinery needs, and it is the forge's: the
+     * refspec names the branch, the URL is the one this forge named when it
+     * claimed the project, and the credential rides the environment — the
+     * checkout's config stays untouched, as with every other transfer. A
+     * remote without that branch answers "couldn't find remote ref", which is
+     * the ordinary news of a ticket branch never pushed: said quietly, no
+     * ref left behind. Anything else is a failed transfer, and it throws.
+     */
+    fetchBranch(repo: RepoRef, directory: string, branch: string): Promise<void>;
+    /**
+     * Move aivi's commits to the remote, as the app and never as the person at
+     * the keyboard. Plain when the remote fast-forwards; with a
+     * `--force-with-lease` keyed on the commit the orchestrator just fetched
+     * when the divergence is the worker's own rewrite — the force replaces
+     * exactly that commit and nothing a person added since.
+     */
+    push(repo: RepoRef, worktree: string, branch: string, options?: {
+        lease?: string;
+    }): Promise<void>;
+    /**
+     * Open the pull request that stands for the branch. The base is the
+     * repository's own default branch: that is where a pull request belongs
+     * unless a person said otherwise, and aivi has no place to have been
+     * told.
+     */
+    openPr(repo: RepoRef, branch: string, pr: {
+        author: string;
+        title: string;
+        body: string;
+    }): Promise<PrFacts>;
+    /** Every branch, pruned, refs only: the fresh view `aivi_sync` gives the
+     *  worker and the push's lease starts from. Same transfer as every
+     *  other — the URL this forge named, the credential in the environment,
+     *  nothing left in the checkout's config. */
+    fetchRefs(repo: RepoRef, directory: string): Promise<void>;
+}
+/** The forge for one installed app. */
+/** The forge over one authenticated app: the API reads and the git transfers.
+ *  `git` is the disk crossing a test answers; production leaves it alone. */
+export declare function createGitHubForge(app: GitHubApp, options?: {
+    log?: Logger;
+    git?: GitRunner;
+}): GitHubForge;

package/dist/forge.js

@@ -0,0 +1,410 @@
+/** The `Forge` contract, answered to GitHub. Reads and writes over the API —
+ *  the facts git cannot see from a clone: which pull request stands for a
+ *  branch, what its review threads and conversation say, whether the base
+ *  would take the merge — and the posts aivi makes back: a thread answer, a
+ *  plain comment, a review with inline findings — plus the transfers the
+ *  remote boundary belongs to: fetching branches and checkouts, and moving
+ *  aivi's own commits out.
+ *
+ *  Every call here is made **as the app** through one installation token, and
+ *  every transfer carries that token in the command's own environment: a push
+ *  never runs with the human's keychain, and no credential is written into a
+ *  repository. What aivi does *locally* — creating a worktree, committing in
+ *  one — is not on this class and never was a forge's business.
+ */
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getLogger } from '@aivi/core';
+import { gitCredential, parseWorker, runGit, signComment } from '@aivi/github';
+import { httpsRemote, isGitHub, parseRemote } from './remote.js';
+/** Who and what, out of the opaque `RepoRef` aivi hands back: the two parts of
+ *  the forge's own name for a repository, which is all an API call needs. The
+ *  remote URL is a separate matter — only a transfer reads it, and it reads it
+ *  as the forge left it. */
+function address(repo) {
+    const [owner, name] = repo.id.split('/');
+    if (!owner || !name)
+        throw new Error(`forge-github: ${repo.id} is not a repository this forge named`);
+    return { owner, repo: name };
+}
+/** A pull request, in aivi's words. `id` is the pull number as GitHub's own
+ *  string: what aivi carries and hands back, never interprets. The REST list
+ *  read does not compute whether the merge is clean, and this forge does not
+ *  guess what GitHub has not said: `unknown`. */
+function prFacts(pull) {
+    return {
+        id: String(pull.number),
+        url: pull.html_url,
+        title: pull.title,
+        state: pull.state,
+        branch: pull.head.ref,
+        mergeable: 'unknown',
+    };
+}
+/** The review conversation in one read. GitHub keeps thread *resolution* in
+ *  GraphQL alone — the REST review-comment endpoints show the comments but not
+ *  the thread that holds them — so this is the shape of the answer, not a
+ *  preference for one API over another. */
+const REVIEW_FACTS_QUERY = /* GraphQL */ `
+  query ReviewFacts($owner: String!, $repo: String!, $number: Int!, $threads: Int!, $comments: Int!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequest(number: $number) {
+        number
+        url
+        title
+        state
+        headRefName
+        mergeable
+        reviews(last: 50) {
+          nodes {
+            state
+            author { login __typename }
+          }
+        }
+        reviewThreads(first: $threads) {
+          pageInfo { hasNextPage }
+          nodes {
+            id
+            isResolved
+            isOutdated
+            path
+            comments(first: $comments) {
+              nodes {
+                body
+                author { login __typename }
+              }
+            }
+          }
+        }
+        comments(first: $comments) {
+          pageInfo { hasNextPage }
+          nodes {
+            body
+            createdAt
+            author { login __typename }
+          }
+        }
+      }
+    }
+  }
+`;
+/** Post a reply into an open thread. */
+const REPLY_MUTATION = /* GraphQL */ `
+  mutation ThreadReply($threadId: ID!, $body: String!) {
+    addPullRequestReviewThreadReply(input: { pullRequestReviewThreadId: $threadId, body: $body }) {
+      comment {
+        id
+      }
+    }
+  }
+`;
+/** Close the thread the reply answered. GitHub offers no single mutation that
+ *  does both, so an answer is two round trips: the words, then the resolution. */
+const RESOLVE_MUTATION = /* GraphQL */ `
+  mutation ResolveThread($threadId: ID!) {
+    resolveReviewThread(input: { threadId: $threadId }) {
+      thread {
+        id
+        isResolved
+      }
+    }
+  }
+`;
+/** Who wrote it, in aivi's words. A GitHub bot's login ends in `[bot]` and its
+ *  author node is a `Bot`; a deleted account answers `null` and leaves nothing
+ *  to attribute. */
+function authorOf(node) {
+    const login = node?.login ?? 'deleted';
+    return { login, bot: node?.__typename === 'Bot' || login.endsWith('[bot]') };
+}
+/** The same, with the worker role read back out of what the comment itself
+ *  says — the signature is the only carrier, and it is one a human reads. */
+function authorOfComment(comment) {
+    const author = authorOf(comment.author);
+    const worker = parseWorker(comment.body);
+    return worker ? { ...author, worker } : author;
+}
+/** One open thread, or nothing when it is settled: a wake takes what is open
+ *  and owes nothing for what a person already resolved. */
+function openThread(node) {
+    if (node.isResolved)
+        return undefined;
+    const [first, ...rest] = node.comments.nodes;
+    return {
+        id: node.id,
+        ...(node.path ? { path: node.path } : {}),
+        state: node.isOutdated ? 'outdated' : 'open',
+        question: first?.body ?? '',
+        replies: rest.map(comment => ({ author: authorOfComment(comment), body: comment.body })),
+    };
+}
+export class GitHubForge {
+    app;
+    log;
+    git;
+    constructor(app, options = {}) {
+        this.app = app;
+        this.log = options.log ?? getLogger(['aivi', 'forge-github']);
+        this.git = options.git ?? runGit;
+    }
+    /** The checkout's own `origin`, read locally: a project aivi has never
+     *  cloned is not less a project for it. Anything that is not a GitHub
+     *  repository — another host, a local path, no remote at all — is answered
+     *  with silence, because the answer belongs to another forge or to nobody. */
+    async repoFor(project) {
+        const origin = await this.git(project.directory, ['remote', 'get-url', 'origin']);
+        if (!origin.ok)
+            return undefined;
+        const remote = parseRemote(origin.stdout);
+        if (!remote || !isGitHub(remote))
+            return undefined;
+        // An ssh origin is said, not fixed: the person chose that transport for
+        // their own reasons, and aivi's transfers go over HTTPS regardless.
+        if (remote.ssh)
+            this.log.debug('origin.ssh', { project: project.id, origin: origin.stdout, used: httpsRemote(remote) });
+        return { id: `${remote.owner}/${remote.repo}`, remote: httpsRemote(remote) };
+    }
+    /** The newest pull request over the branch: a branch whose first attempt was
+     *  closed and reopened has a live one and a dead one, and aivi means the
+     *  live one. */
+    async prForBranch(repo, branch) {
+        const { owner, repo: name } = address(repo);
+        const { data: found } = await this.app.octokit.rest.pulls.list({
+            owner,
+            repo: name,
+            state: 'all',
+            head: `${owner}:${branch}`,
+            per_page: 5,
+            direction: 'desc',
+        });
+        const newest = found[0];
+        return newest ? prFacts(newest) : undefined;
+    }
+    /** Everything a review wake needs, in one read: the state of the approvals,
+     *  the threads still open, and the plain conversation comments — context
+     *  the worker reads but is never gated on. A pull request aivi cannot see
+     *  is said, not answered empty — an empty review sends a worker away
+     *  believing it is done. And a read that could not hold everything is
+     *  **said too**: `hasNextPage` on either connection is a
+     *  loud `review.facts.truncated`, the same word Linear keeps for its own
+     *  wide board reads — silence here leaves a worker owing answers it
+     *  believed were gathered. */
+    async reviewFeedback(repo, pr) {
+        const { owner, repo: name } = address(repo);
+        const answer = await this.app.octokit.graphql(REVIEW_FACTS_QUERY, { owner, repo: name, number: Number(pr.id), threads: 100, comments: 100 });
+        const pull = answer.repository?.pullRequest;
+        if (!pull)
+            throw new Error(`forge-github: pull request #${pr.id} of ${repo.id} is not visible to installation #${this.app.installationId}`);
+        const cut = [
+            ...(pull.reviewThreads.pageInfo.hasNextPage ? ['review threads'] : []),
+            ...(pull.comments.pageInfo.hasNextPage ? ['conversation comments'] : []),
+        ];
+        if (cut.length)
+            this.log.warn('review.facts.truncated', { repo: repo.id, pr: pr.id, held: cut.join(' and ') });
+        return {
+            pr: {
+                id: String(pull.number),
+                url: pull.url,
+                title: pull.title,
+                state: pull.state,
+                branch: pull.headRefName,
+                // GitHub's own word, in aivi's three: MERGEABLE is clean,
+                // CONFLICTING is dirty, and a mergeability GitHub has not computed
+                // yet (it computes on demand) is said as unknown, not guessed.
+                mergeable: pull.mergeable === 'MERGEABLE' ? 'clean' : pull.mergeable === 'CONFLICTING' ? 'dirty' : 'unknown',
+            },
+            reviews: pull.reviews.nodes.map(review => ({ author: authorOf(review.author), state: review.state })),
+            threads: pull.reviewThreads.nodes.flatMap(node => {
+                const thread = openThread(node);
+                return thread ? [thread] : [];
+            }),
+            comments: pull.comments.nodes.map(comment => ({
+                author: authorOfComment(comment),
+                body: comment.body,
+                createdAt: comment.createdAt,
+            })),
+        };
+    }
+    /** Answer the thread as aivi, then resolve it: the worker's words, signed
+     *  with the role that wrote them, closing the person's question. */
+    async resolveThread(repo, _pr, threadId, reply) {
+        await this.app.octokit.graphql(REPLY_MUTATION, { threadId, body: signComment(reply.text, reply.author) });
+        await this.app.octokit.graphql(RESOLVE_MUTATION, { threadId });
+        this.log.info('review.answered', { repo: repo.id, thread: threadId, worker: reply.author });
+    }
+    /** A plain conversation comment, signed like every aivi post: what the
+     *  worker says when there is no thread to answer. */
+    async commentPr(repo, pr, comment) {
+        const { owner, repo: name } = address(repo);
+        await this.app.octokit.rest.issues.createComment({
+            owner,
+            repo: name,
+            issue_number: Number(pr.id),
+            body: signComment(comment.text, comment.author),
+        });
+        this.log.info('pull.commented', { repo: repo.id, pull: pr.id, worker: comment.author });
+    }
+    /** The review agent's teeth: findings on the lines themselves, which the
+     *  platform shows as review threads — agent feedback that the next round's
+     *  worker owes answers on. Every inline body carries the signature like
+     *  every aivi post, so a wake can tell its own findings from a human's. */
+    async submitReview(repo, pr, review) {
+        const { owner, repo: name } = address(repo);
+        await this.app.octokit.rest.pulls.createReview({
+            owner,
+            repo: name,
+            pull_number: Number(pr.id),
+            event: review.state,
+            body: signComment(review.body, review.author),
+            ...(review.comments
+                ? {
+                    comments: review.comments.map(finding => ({
+                        path: finding.path,
+                        ...(finding.line === undefined ? {} : { line: finding.line }),
+                        body: signComment(finding.body, review.author),
+                    })),
+                }
+                : {}),
+        });
+        this.log.info('review.submitted', {
+            repo: repo.id,
+            pull: pr.id,
+            state: review.state,
+            worker: review.author,
+            findings: review.comments?.length ?? 0,
+        });
+    }
+    /** The URL and credential for one transfer. The URL is the one this forge
+     *  named when it claimed the project — HTTPS, whatever the checkout's own
+     *  `origin` says, because an installation token authenticates HTTPS and
+     *  nothing else — and it is used as given: re-reading it here would let a
+     *  checkout's config decide where aivi's credential is sent. */
+    async transfer(repo) {
+        if (!repo.remote)
+            throw new Error(`forge-github: ${repo.id} came with no remote to reach`);
+        return { url: repo.remote, env: gitCredential(await this.app.gitToken()) };
+    }
+    /**
+     * Fetch, then fast-forward — and stop at that. Every case that would need a
+     * decision is reported with its reason: `source/` is the clean checkout
+     * aivi indexes, not a working directory, so aivi never merges a conflict,
+     * never discards a person's edit, and never rewrites history.
+     *
+     * The fetch names its refspec instead of trusting `origin`'s: the URL aivi
+     * authenticates is HTTPS, which for an ssh checkout is not the URL
+     * configured, and a fetch by URL updates only what its refspec names.
+     */
+    async syncSource(repo, directory) {
+        if (!(await stat(join(directory, '.git')).catch(() => null)))
+            return { state: 'held', reason: 'not a git checkout' };
+        const branch = await this.git(directory, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+        if (!branch.ok || !branch.stdout)
+            return { state: 'held', reason: 'detached HEAD' };
+        const dirty = await this.git(directory, ['status', '--porcelain']);
+        if (!dirty.ok)
+            return { state: 'held', reason: dirty.message };
+        if (dirty.stdout)
+            return { state: 'held', reason: 'local changes in source/' };
+        const name = `refs/remotes/origin/${branch.stdout}`;
+        const transport = await this.transfer(repo);
+        const fetched = await this.git(directory, ['fetch', '--quiet', transport.url, `+${branch.stdout}:${name}`], {
+            env: transport.env,
+        });
+        if (!fetched.ok)
+            return { state: 'held', reason: `fetch failed: ${fetched.message}` };
+        const from = await this.git(directory, ['rev-parse', 'HEAD']);
+        if (!from.ok)
+            return { state: 'held', reason: from.message };
+        const to = await this.git(directory, ['rev-parse', name]);
+        if (!to.ok)
+            return { state: 'held', reason: `branch ${branch.stdout} has no upstream` };
+        if (from.stdout === to.stdout)
+            return { state: 'current', from: from.stdout, to: to.stdout };
+        const ahead = await this.git(directory, ['merge-base', '--is-ancestor', 'HEAD', name]);
+        if (!ahead.ok)
+            return { state: 'held', reason: `${branch.stdout} and ${name} have diverged; a person must decide` };
+        const merged = await this.git(directory, ['merge', '--ff-only', '--quiet', name]);
+        if (!merged.ok)
+            return { state: 'held', reason: merged.message };
+        this.log.info('source.synced', { repo: repo.id, from: from.stdout, to: to.stdout });
+        return { state: 'updated', from: from.stdout, to: to.stdout };
+    }
+    /**
+     * The one fetch the worktree machinery needs, and it is the forge's: the
+     * refspec names the branch, the URL is the one this forge named when it
+     * claimed the project, and the credential rides the environment — the
+     * checkout's config stays untouched, as with every other transfer. A
+     * remote without that branch answers "couldn't find remote ref", which is
+     * the ordinary news of a ticket branch never pushed: said quietly, no
+     * ref left behind. Anything else is a failed transfer, and it throws.
+     */
+    async fetchBranch(repo, directory, branch) {
+        const transport = await this.transfer(repo);
+        const fetched = await this.git(directory, ['fetch', '--quiet', transport.url, `+refs/heads/${branch}:refs/remotes/origin/${branch}`], { env: transport.env });
+        if (fetched.ok)
+            return;
+        if (/couldn't find remote ref/i.test(fetched.message)) {
+            this.log.debug('branch.absent', { repo: repo.id, branch });
+            return;
+        }
+        throw new Error(`forge-github: fetching ${branch} from ${repo.id} failed: ${fetched.message}`);
+    }
+    /**
+     * Move aivi's commits to the remote, as the app and never as the person at
+     * the keyboard. Plain when the remote fast-forwards; with a
+     * `--force-with-lease` keyed on the commit the orchestrator just fetched
+     * when the divergence is the worker's own rewrite — the force replaces
+     * exactly that commit and nothing a person added since.
+     */
+    async push(repo, worktree, branch, options = {}) {
+        const transport = await this.transfer(repo);
+        const pushed = await this.git(worktree, [
+            'push',
+            '--quiet',
+            ...(options.lease ? [`--force-with-lease=refs/heads/${branch}:${options.lease}`] : []),
+            transport.url,
+            `HEAD:refs/heads/${branch}`,
+        ], { env: transport.env });
+        if (!pushed.ok)
+            throw new Error(`forge-github: pushing ${branch} to ${repo.id} failed${options.lease ? ' (the lease no longer matches: the remote moved since the last fetch)' : ''}: ${pushed.message}`);
+        this.log.info('branch.pushed', { repo: repo.id, branch, ...(options.lease ? { forced: true } : {}) });
+    }
+    /**
+     * Open the pull request that stands for the branch. The base is the
+     * repository's own default branch: that is where a pull request belongs
+     * unless a person said otherwise, and aivi has no place to have been
+     * told.
+     */
+    async openPr(repo, branch, pr) {
+        const { owner, repo: name } = address(repo);
+        const target = await this.app.repository(owner, name);
+        if (!target)
+            throw new Error(`forge-github: ${repo.id} is not readable through installation #${this.app.installationId}, so a pull request has no base`);
+        const { data: created } = await this.app.octokit.rest.pulls.create({
+            owner,
+            repo: name,
+            head: branch,
+            base: target.defaultBranch,
+            title: pr.title,
+            body: signComment(pr.body, pr.author),
+        });
+        this.log.info('pull.opened', { repo: repo.id, pull: created.number, worker: pr.author });
+        return prFacts(created);
+    }
+    /** Every branch, pruned, refs only: the fresh view `aivi_sync` gives the
+     *  worker and the push's lease starts from. Same transfer as every
+     *  other — the URL this forge named, the credential in the environment,
+     *  nothing left in the checkout's config. */
+    async fetchRefs(repo, directory) {
+        const transport = await this.transfer(repo);
+        const fetched = await this.git(directory, ['fetch', '--prune', '--quiet', transport.url, '+refs/heads/*:refs/remotes/origin/*'], { env: transport.env });
+        if (!fetched.ok)
+            throw new Error(`forge-github: fetching ${repo.id} failed: ${fetched.message}`);
+    }
+}
+/** The forge for one installed app. */
+/** The forge over one authenticated app: the API reads and the git transfers.
+ *  `git` is the disk crossing a test answers; production leaves it alone. */
+export function createGitHubForge(app, options = {}) {
+    return new GitHubForge(app, options);
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { ForgeGithubConfig } from './config.ts';
+export { forgeGithubSchema, plugin } from './config.ts';
+export { createGitHubForge, GitHubForge } from './forge.ts';
+export { createForgeGithubModule } from './module.ts';
+export type { GitHubRemote } from './remote.ts';
+export { GITHUB_HOST, httpsRemote, isGitHub, parseRemote } from './remote.ts';
+export { suggestedProjectId } from './setup-project.ts';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { forgeGithubSchema, plugin } from './config.js';
+export { createGitHubForge, GitHubForge } from './forge.js';
+export { createForgeGithubModule } from './module.js';
+export { GITHUB_HOST, httpsRemote, isGitHub, parseRemote } from './remote.js';
+export { suggestedProjectId } from './setup-project.js';

package/dist/module.d.ts

@@ -0,0 +1,2 @@
+import type { AiviModule } from '@aivi/plugin';
+export declare function createForgeGithubModule(): AiviModule;

package/dist/module.js

@@ -0,0 +1,41 @@
+/** The `forge-github` module: the app, proven at boot, registered, standing by.
+ *
+ *  The module's work is to **prove the credential at boot and register the
+ *  answer**: an app whose key was rotated, an installation that was revoked
+ *  or was never made, a grant that turned into two — each is said once,
+ *  loudly, where `/status` shows it, rather than at the first push a worker
+ *  is waiting on. The credential is the environment's (`GITHUB_APP_ID`,
+ *  `GITHUB_APP_PRIVATE_KEY` in `<home>/.env`), shared with every other plugin
+ *  that speaks GitHub (ruled 2026-10-07). The registry question — *"who owns
+ *  this project's remote?"* — is asked now (built 2026-10-02): the projects-sync
+ *  task was the first, and a checkout whose `origin` this app recognises syncs
+ *  through this forge, authenticated as its own installation. The push asks
+ *  it today — the worker's `aivi_pr` call ends here — and the review gather
+ *  will ask it when it comes.
+ */
+import { githubApp } from '@aivi/github';
+import { createGitHubForge } from './forge.js';
+async function startForge(services) {
+    const log = services.log.getChild('forge-github');
+    // Every failure here is a ConfigurationError naming what to fix on GitHub or
+    // in .env: the module goes to error, `/status` says so, and nothing retries.
+    // The client is the process's one app: a tracker module started beside this
+    // one shares the connection rather than paying the JWT and installation
+    // reads again.
+    const app = await githubApp({ log });
+    const unregister = services.forges.register(createGitHubForge(app, { log }));
+    log.info('ready', {
+        installation: app.installationId,
+        account: app.accountLogin,
+        note: 'registered on the forge registry; the host asks who owns each remote',
+    });
+    return {
+        // No routes, no tasks, no timers: only the registration to give back.
+        stop: async () => {
+            unregister();
+        },
+    };
+}
+export function createForgeGithubModule() {
+    return { id: 'forge-github', start: services => startForge(services) };
+}

package/dist/remote.d.ts

@@ -0,0 +1,45 @@
+/** The facts aivi reads off a git remote's URL. Kept out of `github.ts`
+ *  because none of it needs a credential, a network, or octokit: this is what
+ *  a checkout says about itself, and what aivi answers with.
+ *
+ *  What aivi answers with matters because an installation token authenticates
+ *  **HTTPS and nothing else** — GitHub's ssh transport takes a key, which is a
+ *  human's credential. So aivi never transfers through a checkout's own
+ *  `origin`: it names the HTTPS URL of the same repository on the command line,
+ *  beside the credential it supplies. A person who cloned with ssh keeps their
+ *  `origin` exactly as they left it, and no byte of aivi's credential is
+ *  written to the repository's config.
+ */
+/** One repository, as its remote names it. `host` is lower-cased (DNS is);
+ *  `owner` and `repo` keep their case, which GitHub treats as display and
+ *  resolves either way. */
+export interface GitHubRemote {
+    host: string;
+    owner: string;
+    repo: string;
+    /** True when the URL is an ssh form — the transport aivi cannot use. */
+    ssh: boolean;
+}
+/** The one host aivi speaks to as GitHub. GitHub Enterprise Server is a
+ *  different host with a different install, not a detail of this parse. */
+export declare const GITHUB_HOST = "github.com";
+/**
+ * Read a remote URL for what aivi can use: `owner/repo` and which transport it
+ * names. Understands the scp-like ssh form (`git@github.com:owner/repo.git`),
+ * `ssh://`, `https://` and `http://`, each with or without the `.git` suffix,
+ * and the bare `owner/repo` shorthand a person types for a GitHub repository
+ * (no transport to speak of, so it reads as https). Undefined for anything
+ * that is not a two-segment repository path — a repository on another host,
+ * a URL with a port or a nested path, or a local path, which is a checkout
+ * with no remote to speak of.
+ */
+export declare function parseRemote(url: string): GitHubRemote | undefined;
+/** True when the remote is GitHub's own host — the only one this forge
+ *  claims. Another host is another forge's turn, said silently: a project on
+ *  GitLab is not an error here. */
+export declare function isGitHub(remote: GitHubRemote): boolean;
+/** The URL aivi authenticates: the same repository over HTTPS. Every transfer
+ *  names this URL on the command line instead of a remote's name, so the
+ *  credential aivi supplies is the one git uses — no rewrite of the checkout's
+ *  own config, and no chance of a stored credential being preferred instead. */
+export declare function httpsRemote(remote: GitHubRemote): string;

package/dist/remote.js

@@ -0,0 +1,92 @@
+/** The facts aivi reads off a git remote's URL. Kept out of `github.ts`
+ *  because none of it needs a credential, a network, or octokit: this is what
+ *  a checkout says about itself, and what aivi answers with.
+ *
+ *  What aivi answers with matters because an installation token authenticates
+ *  **HTTPS and nothing else** — GitHub's ssh transport takes a key, which is a
+ *  human's credential. So aivi never transfers through a checkout's own
+ *  `origin`: it names the HTTPS URL of the same repository on the command line,
+ *  beside the credential it supplies. A person who cloned with ssh keeps their
+ *  `origin` exactly as they left it, and no byte of aivi's credential is
+ *  written to the repository's config.
+ */
+/** The `.git` transport suffix, which names nothing. */
+const stripSuffix = (path) => (path.endsWith('.git') ? path.slice(0, -4) : path);
+/** The one host aivi speaks to as GitHub. GitHub Enterprise Server is a
+ *  different host with a different install, not a detail of this parse. */
+export const GITHUB_HOST = 'github.com';
+/** The shorthand a person types when they mean a GitHub repository: two
+ *  path segments and nothing else. GitHub's own names are letters, digits,
+ *  dots, dashes and underscores; a lone `.` or `..` is a relative path, so
+ *  the segments may not be all-dots. */
+const BARE = /^([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+)$/;
+const bareRemote = (raw) => {
+    const bare = BARE.exec(raw);
+    if (!bare)
+        return undefined;
+    const [, owner, repo] = bare;
+    if (/^\.+$/.test(owner ?? '') || /^\.+$/.test(repo ?? ''))
+        return undefined;
+    return { host: GITHUB_HOST, owner: owner, repo: stripSuffix(repo), ssh: false };
+};
+/**
+ * Read a remote URL for what aivi can use: `owner/repo` and which transport it
+ * names. Understands the scp-like ssh form (`git@github.com:owner/repo.git`),
+ * `ssh://`, `https://` and `http://`, each with or without the `.git` suffix,
+ * and the bare `owner/repo` shorthand a person types for a GitHub repository
+ * (no transport to speak of, so it reads as https). Undefined for anything
+ * that is not a two-segment repository path — a repository on another host,
+ * a URL with a port or a nested path, or a local path, which is a checkout
+ * with no remote to speak of.
+ */
+export function parseRemote(url) {
+    const raw = url.trim();
+    if (!raw || raw.startsWith('-'))
+        return undefined;
+    // `git@github.com:owner/repo.git` — scp syntax, no scheme to parse.
+    const scp = /^([^/@\s]+)@([^/:]+):(.+)$/.exec(raw);
+    if (scp && !raw.includes('://')) {
+        const [, , host, path] = scp;
+        const segments = stripSuffix(path ?? '')
+            .split('/')
+            .filter(Boolean);
+        if (!host || segments.length !== 2)
+            return undefined;
+        return { host: host.toLowerCase(), owner: segments[0], repo: segments[1], ssh: true };
+    }
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        // No scheme to parse: the only other thing that names a repository is the
+        // bare `owner/repo`, which can only mean the one host this forge speaks.
+        return bareRemote(raw);
+    }
+    if (!['https:', 'http:', 'ssh:'].includes(parsed.protocol))
+        return undefined;
+    if (parsed.port)
+        return undefined;
+    const segments = stripSuffix(parsed.pathname).split('/').filter(Boolean);
+    if (segments.length !== 2)
+        return undefined;
+    return {
+        host: parsed.hostname.toLowerCase(),
+        owner: segments[0],
+        repo: segments[1],
+        ssh: parsed.protocol === 'ssh:',
+    };
+}
+/** True when the remote is GitHub's own host — the only one this forge
+ *  claims. Another host is another forge's turn, said silently: a project on
+ *  GitLab is not an error here. */
+export function isGitHub(remote) {
+    return remote.host === GITHUB_HOST;
+}
+/** The URL aivi authenticates: the same repository over HTTPS. Every transfer
+ *  names this URL on the command line instead of a remote's name, so the
+ *  credential aivi supplies is the one git uses — no rewrite of the checkout's
+ *  own config, and no chance of a stored credential being preferred instead. */
+export function httpsRemote(remote) {
+    return `https://${GITHUB_HOST}/${remote.owner}/${remote.repo}.git`;
+}

package/dist/setup-project.d.ts

@@ -0,0 +1,7 @@
+import { type ProjectContributor } from '@aivi/plugin';
+/** The project name a repository suggests: GitHub's `My-Repo` becomes aivi's
+ *  `my-repo`, the shape a project directory takes. Anything the id rule does
+ *  not allow becomes a dash, and a name that no longer starts with a letter
+ *  keeps one. */
+export declare function suggestedProjectId(repoName: string): string;
+export declare const contributor: ProjectContributor;

package/dist/setup-project.js

@@ -0,0 +1,138 @@
+/** The forge's part in `aivi projects add`: what repository this project is,
+ *  and its checkout. The runner walks core's roles and calls this for the
+ *  `forge` role; everything GitHub-specific lives in this file, and the
+ *  questions are asked with the runner's own clack.
+ *
+ *  The clone is the reason the role is the forge's and not aivi's: cloning
+ *  reaches `origin`, and reaching `origin` authenticates. So aivi clones as
+ *  **its own app** through the one installation token, in the command's own
+ *  environment — the person's keychain is never offered, and no token is left
+ *  in the checkout for someone to find later.
+ */
+import { mkdir, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { getLogger, PROJECT_ID } from '@aivi/core';
+import { gitCredential, githubApp, runGit } from '@aivi/github';
+import { PluginSetupCancelled } from '@aivi/plugin';
+import { httpsRemote, isGitHub, parseRemote } from './remote.js';
+/** The project name a repository suggests: GitHub's `My-Repo` becomes aivi's
+ *  `my-repo`, the shape a project directory takes. Anything the id rule does
+ *  not allow becomes a dash, and a name that no longer starts with a letter
+ *  keeps one. */
+export function suggestedProjectId(repoName) {
+    const folded = repoName.toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+    return /^[a-z]/.test(folded) ? folded : `p-${folded}`;
+}
+/** A prompt the person cancelled is not an answer: nothing further is written
+ *  and the runner says the one cancel line. */
+async function settled(ctx, answer) {
+    const value = await answer;
+    if (ctx.prompts.isCancel(value))
+        throw new PluginSetupCancelled('a prompt was cancelled');
+    return value;
+}
+/** The repository asked for and read for what it is. Undefined when the answer
+ *  names no GitHub repository at all: a non-GitHub host is said plainly, since
+ *  a person typing a GitLab URL means it, and silence would lose the project.
+ *
+ *  The app is asked what it was granted before the person is asked anything:
+ *  a pick-list of the real grant beats typing a name from memory, and a
+ *  mistake is impossible. A grant that cannot be listed is no failure — the
+ *  typed answer's own probe referees it anyway — so the text prompt stays as
+ *  the fallback, asking the very question the list would have. */
+async function askRepository(ctx, app) {
+    const spinner = ctx.prompts.spinner();
+    spinner.start('Asking the app which repositories it can see');
+    let granted = [];
+    try {
+        granted = (await app.repositories()).map(repo => repo.id);
+        spinner.stop(`The app can see ${granted.length} repositor${granted.length === 1 ? 'y' : 'ies'}`);
+    }
+    catch (error) {
+        spinner.stop(`Could not list the app's repositories: ${error instanceof Error ? error.message : error}`);
+    }
+    const answer = granted.length
+        ? await settled(ctx, ctx.prompts.autocomplete({
+            message: 'Which GitHub repository is this project?',
+            options: granted.map(id => ({ value: id, label: id })),
+            maxItems: 12,
+        }))
+        : await settled(ctx, ctx.prompts.text({
+            message: 'Which GitHub repository is this project?',
+            placeholder: 'owner/repo, or its URL',
+            validate: value => (parseRemote(value ?? '') ? undefined : 'Give it as owner/repo, or as a github.com URL'),
+        }));
+    const remote = parseRemote(String(answer).trim());
+    if (!remote)
+        return undefined;
+    if (!isGitHub(remote))
+        throw new Error(`${remote.host} is not github.com, and this forge speaks github.com repositories only. Clone that project by hand, or point aivi at a different forge.`);
+    return remote;
+}
+export const contributor = {
+    role: 'forge',
+    async setup(ctx) {
+        const log = getLogger(['aivi', 'forge-github']);
+        // The app is the home's: the credential comes from <home>/.env, the same
+        // one the forge module and the tracker speak through (ruled 2026-10-07).
+        const app = await githubApp({ log });
+        const remote = await askRepository(ctx, app);
+        if (!remote)
+            throw new Error('no repository named');
+        const id = `${remote.owner}/${remote.repo}`;
+        // Proven under the grant before a directory is made: GitHub answers 404 for
+        // a repository the app was not given, so this is also the answer to "is
+        // this repository in the installation's set".
+        const seen = await app.repository(remote.owner, remote.repo);
+        if (!seen)
+            throw new Error(`the app ${app.appSlug} cannot see ${id} through installation #${app.installationId}. Grant it that repository on GitHub and run this again.`);
+        await ctx.prompts.log.message(`The app reads ${id} (default branch ${seen.defaultBranch}).`);
+        const suggestion = suggestedProjectId(remote.repo);
+        // Enter takes the suggested name. clack 1.x runs `validate` on the raw
+        // input **before** `finalize` applies `defaultValue`, so a validate
+        // that refuses '' makes the default dead code. '' passes validation
+        // here; the default is folded in below, where it takes effect.
+        let projectId = ctx.projectId ? String(ctx.projectId) : '';
+        if (!projectId) {
+            const answer = await settled(ctx, ctx.prompts.text({
+                message: 'Project name',
+                placeholder: suggestion,
+                defaultValue: suggestion,
+                validate: value => value === undefined || !value.trim() || PROJECT_ID.test(value.trim())
+                    ? undefined
+                    : 'lowercase letters, digits, dashes and underscores, starting with a letter',
+            }));
+            projectId = String(answer).trim() || suggestion;
+        }
+        const source = join(ctx.home, 'projects', projectId, 'source');
+        // A checkout already there belongs to its owner. The same repository means
+        // aivi found what it was looking for and takes it as it stands; a different
+        // one means aivi would be writing a stranger's remote into a person's
+        // working copy, which is a decision and never a default.
+        if (await stat(join(source, '.git')).catch(() => null)) {
+            const origin = await runGit(source, ['remote', 'get-url', 'origin']);
+            const found = origin.ok ? parseRemote(origin.stdout) : undefined;
+            if (found && `${found.owner}/${found.repo}` === id) {
+                await ctx.prompts.log.message(`projects/${projectId}/source is already a checkout of ${id}; left as it is.`);
+                return { id: projectId, cloned: true, repository: id };
+            }
+            throw new Error(`projects/${projectId}/source is a checkout of ${found ? `${found.owner}/${found.repo}` : 'something that is not a GitHub repository'}. Move it aside, or choose a project name that has no checkout yet.`);
+        }
+        const credential = gitCredential(await app.gitToken());
+        await mkdir(dirname(source), { recursive: true });
+        const spinner = ctx.prompts.spinner();
+        spinner.start(`cloning ${id}…`);
+        const cloned = await runGit(dirname(source), ['clone', '--quiet', httpsRemote(remote), source], {
+            env: credential,
+        });
+        // A clone that failed leaves a project with no checkout, and the runner
+        // would then write its "no source" note over the half-made directory: the
+        // flow stops here rather than reporting a project that is not one.
+        if (!cloned.ok) {
+            spinner.stop(`could not clone ${id}: ${cloned.message}`);
+            throw new Error(`clone of ${id} failed: ${cloned.message}`);
+        }
+        spinner.stop(`Cloned ${id} into projects/${projectId}/source.`);
+        return { id: projectId, cloned: true, repository: id };
+    },
+};

package/dist/setup.d.ts

@@ -0,0 +1,23 @@
+/** The setup `aivi add @aivi/forge-github` runs. It guides what a person has
+ *  to do on GitHub — create the app, give aivi its key, select the
+ *  repositories — and then proves each fact at GitHub before writing a byte:
+ *  that the id and the key belong to one app, that exactly one installation
+ *  exists, and that the installation really reads a repository, by reading
+ *  that repository's pull requests through it.
+ *
+ *  The app's identity lands in `<home>/.env` — `GITHUB_APP_ID` beside
+ *  `GITHUB_APP_PRIVATE_KEY` (ruled 2026-10-07): the forge and the tracker are
+ *  one app, so the credential is a home fact, not a plugin block's. The
+ *  guide and its two questions are therefore `@aivi/github`'s (`appIdentity`),
+ *  shared with the tracker's installer; when the home already holds the
+ *  identity, nothing is asked. The block written to `config.json` is empty:
+ *  it only marks the forge as configured, which is what makes core offer the
+ *  forge role to a new project.
+ *
+ *  The installation is a human's act and aivi cannot do it: no throwaway
+ *  ticket, no write, is asked of a person to prove the grant — one read is
+ *  enough. Writes are proven once, at the live gate.
+ */
+import type { PluginSetup } from '@aivi/plugin';
+declare const setup: PluginSetup;
+export default setup;

package/dist/setup.js

@@ -0,0 +1,62 @@
+/** The setup `aivi add @aivi/forge-github` runs. It guides what a person has
+ *  to do on GitHub — create the app, give aivi its key, select the
+ *  repositories — and then proves each fact at GitHub before writing a byte:
+ *  that the id and the key belong to one app, that exactly one installation
+ *  exists, and that the installation really reads a repository, by reading
+ *  that repository's pull requests through it.
+ *
+ *  The app's identity lands in `<home>/.env` — `GITHUB_APP_ID` beside
+ *  `GITHUB_APP_PRIVATE_KEY` (ruled 2026-10-07): the forge and the tracker are
+ *  one app, so the credential is a home fact, not a plugin block's. The
+ *  guide and its two questions are therefore `@aivi/github`'s (`appIdentity`),
+ *  shared with the tracker's installer; when the home already holds the
+ *  identity, nothing is asked. The block written to `config.json` is empty:
+ *  it only marks the forge as configured, which is what makes core offer the
+ *  forge role to a new project.
+ *
+ *  The installation is a human's act and aivi cannot do it: no throwaway
+ *  ticket, no write, is asked of a person to prove the grant — one read is
+ *  enough. Writes are proven once, at the live gate.
+ */
+import { getLogger } from '@aivi/core';
+import { appIdentity, GitHubApp } from '@aivi/github';
+const setup = async (ctx) => {
+    const log = getLogger(['aivi', 'forge-github']);
+    ctx.prompts.note([
+        'aivi works on GitHub as its own app, never as you:',
+        'it opens its pull requests and answers review comments as the bot,',
+        'so the work in front of a reviewer is aivi’s and the credit is yours.',
+        '',
+        'You create the app on GitHub and install it on the account that',
+        'holds the repositories. aivi speaks through that one installation.',
+        'It cannot do this part, and it will not write anything until it',
+        'has read a real pull request through the grant.',
+    ].join('\n'), 'The GitHub app aivi works as');
+    // The guide, the App ID and the .pem are the library's (one app, one set of
+    // questions): when the home already holds the identity, nothing is asked.
+    const { appId, privateKey } = await appIdentity(ctx);
+    // The proof below runs in this process, which read `.env` before the key was
+    // in it: hand the credential to the connection directly, so what is tested
+    // here is the bytes that were just written.
+    const app = await GitHubApp.connect({ log, credentials: { appId, privateKey } });
+    await ctx.prompts.log.message(`The key is app ${app.appSlug}’s, installed on ${app.accountLogin} as installation #${app.installationId}.`);
+    // The proof that matters is a read the grant really allows. A repository the
+    // app was not given answers 404, so this is also the answer to "is it in the
+    // installation’s set" — and an installation that reaches no repository is a
+    // grant that has not been aimed at anything.
+    const { data: grant } = await app.octokit.rest.apps.listReposAccessibleToInstallation({ per_page: 100 });
+    if (!grant.repositories.length)
+        throw new Error(`installation #${app.installationId} reaches no repository: on the installation page, choose "Only select repositories" and select the repositories you want to use aivi in`);
+    const first = grant.repositories.find(r => !r.archived) ?? grant.repositories[0];
+    const [owner = '', name = ''] = first.full_name.split('/');
+    const { data: pulls } = await app.octokit.rest.pulls.list({ owner, repo: name, state: 'all', per_page: 3 });
+    await ctx.prompts.log.message(`It reaches ${grant.total_count >= 100 ? 'more than 100' : grant.total_count} repositories; ${first.full_name} answered with ${pulls.length} pull ${pulls.length === 1 ? 'request' : 'requests'}.`);
+    // The block is empty and says so in the summary: the identity lives in
+    // .env, and this byte in config.json only marks the forge as configured.
+    await ctx.writeConfigBlock(['plugins', 'forge-github'], {});
+    return {
+        module: 'forge-github',
+        summary: `The GitHub forge is set up: app ${app.appSlug} works as installation #${app.installationId} on ${app.accountLogin} (identity in .env), and read ${first.full_name} through it.`,
+    };
+};
+export default setup;

package/docs/github.md

@@ -0,0 +1,33 @@
+# GitHub forge — the forge's configuration
+
+`plugins.forge-github` is the GitHub forge's whole setup, and it is **empty**
+(ruled 2026-10-07): `{ "plugins": { "forge-github": {} } }`. The block stands
+as the mark that the forge is configured — core offers the forge role to a
+project only when it is written — and holds no facts. The module runs when
+`@aivi/forge-github` stands in the `aivi-plugins` list.
+
+The app's identity is a **home** fact, not a block's: `GITHUB_APP_ID` (the
+`App ID` number on the app's settings page) and `GITHUB_APP_PRIVATE_KEY` (the
+PEM GitHub handed out when the app was created) both live in `<home>/.env`,
+because the forge and the tracker are **one app** and a plugin block cannot be
+the shared source for two plugins. `aivi add` asks for the id and the .pem
+once: it copies the key into `.env`, and remembers no path.
+The app must also be **installed** — an installation is the grant from the account
+holding the repositories to the app — and aivi speaks through exactly one:
+none is an error carrying the install link, several is an error naming the
+grants and saying which to revoke.
+
+Nothing in this block names a repository. Which repository a project is comes
+from that project's own `origin`, and a checkout whose remote is not a GitHub
+repository simply has no forge: no error, and no pull-request facts. Likewise
+there is no per-project forge section — a forge is asked about a checkout it
+did not create and reads the answer off the checkout. What asks it today is
+the `projects-sync` job (a checkout this forge recognises syncs **through**
+the forge, authenticated as its own installation; the rest stays plain git)
+and the worker's git tools: `aivi_sync` brings the remote's refs in,
+`aivi_push` moves commits (as the forge's own app, fast-forwarding, merging,
+or forcing only a patch-equivalent rewrite), and `aivi_pr` opens the pull
+request when the branch has none; `aivi_review`, `aivi_respond_feedback` and
+`aivi_submit_review` carry the review conversation the same way. A project
+with no forge gets none of these, and the tools say so plainly when they
+are called anyway.

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@aivi/forge-github",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "The GitHub forge for aivi: the remote a project came from, the pull requests over its branches, and the review conversation on them.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./config": {
+      "development": "./src/config.ts",
+      "default": "./dist/config.js"
+    },
+    "./setup": {
+      "development": "./src/setup.ts",
+      "default": "./dist/setup.js"
+    },
+    "./setupProject": {
+      "development": "./src/setup-project.ts",
+      "default": "./dist/setup-project.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=26.1.0 <27"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aivi-hq/aivi.git",
+    "directory": "packages/forge-github"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "tsc -b tsconfig.build.json"
+  },
+  "dependencies": {
+    "@aivi/core": "^0.7.1",
+    "@aivi/github": "^0.0.0",
+    "@aivi/plugin": "^0.1.0",
+    "zod": "4.1.13"
+  },
+  "peerDependencies": {
+    "@aivi/host": "^0.8.1"
+  },
+  "devDependencies": {
+    "@aivi/host": "^0.8.1"
+  }
+}