@open-everywhere/provider-github 0.0.0-stage → 0.1.0

package/agent/surface-parity.ts

@@ -0,0 +1,116 @@
+// GITHUB's surface-parity declaration (OPE-1499). See the core module's header
+// (packages/core/agent/identity/surface-parity.ts) for what the three cell shapes mean.
+//
+// GitHub is a TICKETING surface. A repo holds issues and pull requests, not chat rooms, so the
+// three cross-container verbs and the DM family are absent for a structural reason rather than an
+// unbuilt one — and that distinction is what the reasons below carry.
+
+import type { SurfaceParityDeclaration } from "@open-everywhere/core/agent/adapter-api.js";
+
+export const GITHUB_SURFACE_PARITY: SurfaceParityDeclaration = {
+  // --- registration seams (§7.1) ---------------------------------------------------------------
+  "identity-mapper": "supported",
+  "capability-manifest": "supported",
+  "post-arm": "supported",
+  "wake-origin-codec": "supported",
+  "unified-action-plane": {
+    unsupported:
+      "an issue comment is markdown and carries no component plane at all — GitHub offers no tappable button a bot may render into a timeline comment, so there is nothing for a tap route to receive. The bridged approval posts as prose, which the question bridge already renders complete",
+  },
+  "origin-placement-carry": {
+    unsupported:
+      "the placement is INSIDE the conversation identity: a reply is a comment appended to the issue timeline and the issue IS `threadRef`'s thread key, so there is no 'where inside it' left to name",
+  },
+  "read-adapter": "supported",
+  // 🔴 A POLL, not a delivery, and the note says so because the latency is real. GitHub pushes no
+  // reaction webhook at all, so the arm reads the reactions on the agent's own comments when a
+  // later delivery names their conversation. Only an ADD is observable — the route returns the
+  // reactions that exist, never one that was taken away.
+  "reaction-feedback-ingest": { supported: "polled on the next delivery for that conversation — GitHub pushes no reaction webhook, so a removal is never observed" },
+  "ancillary-ops": "supported",
+  "ambient-engagement-seam": "supported",
+  // `githubWakeAddressing` (channels/github-engagement.ts) carries the admission's own `deliver`
+  // verdict to the `github.dispatched` row, so an engaged follow-up reads `thread-follow` and
+  // unowned issue chatter still reads `channel-watch`. The verdict is floored on
+  // `githubEngagedFollowUpReach`, so an engaged issue on a public or unknown-privacy repo, and an
+  // inline review comment, still write `channel-watch` — the engaged door is shut there. The wake
+  // envelope is untouched: the turn is judged, and the silence bar set, exactly as before
+  // (OPE-1752).
+  "engaged-row-promotion": "supported",
+  // The container and the thread coincide — an issue or pull request IS its own thread — so every
+  // wake this surface diverts is thread-scoped and consults ownership.
+  "owned-thread-ingress": "supported",
+
+  // --- wake legs and conversation shapes -------------------------------------------------------
+  "addressed-leg": "supported",
+  // The ambient supervisor, a different mechanism from the §2.5 registry: the domain opt-in and the
+  // operator vouch decide whether it runs, and the registry has never gated that. The registry does
+  // SUPPRESS it, though — `ambientDelivery` drops a comment in a container `stand_down` marked, and
+  // drops one the native leg now owns (OPE-1501).
+  "ambient-leg": { supported: "the ambient supervisor, not the §2.5 engagement registry" },
+  // `github-catch-up.ts` reads `/issues/:n/comments?since=` for the conversation the seat is woken
+  // on, over the same brokered conversation-read token `read_channel` uses. The vendor's own `since`
+  // filter does the narrowing, so a seat that woke a minute ago pays for a near-empty page.
+  "seat-catch-up": "supported",
+  // The supervisor wake fills the slot with ONE host-composed issue/PR title line, and pours it
+  // through the core seam (github-supervisor.ts). One line is still a pour: a `members-only` domain
+  // must get the same answer here as it gets on the catch-up read beside it.
+  // 🔴 BARE, NOT `{ supported: "…" }` — a noted cell is exempt from the overclaim arm, and this
+  // surface is half of the OPE-1800 class the arm exists to catch.
+  "seat-context-admission": "supported",
+  // A GitHub comment carries no component plane at all — there is no button to tap and no route for
+  // a tap to arrive on. See the roster row for what that costs and where it does NOT cost anything.
+  "approval-card": { unsupported: "an issue/PR comment carries no component plane, so there is no button to render and no route for a tap. A governed act that takes the venue walk is redirected to a card-capable room in the SAME domain, or refused when the domain holds none. The paths OUTSIDE that walk do not: the spend checkpoint (spend/checkpoint.ts `requireSessionContinuation`) fails OPEN here and records the crossing in an audit row instead" },
+  // THE TRACE ARRIVES EVEN THOUGH THE BUTTON CANNOT (OPE-1854). A judge-lifted act posts its
+  // notice here as a plain issue or pull-request comment through the shared road (`postJudgeLiftNotice`), on this
+  // surface's own `SurfaceMessageOps` transport. It carries the overrule as an INSTRUCTION in
+  // words, with the action id a reviewer finds the act by, because no tap can land here.
+  // 🔴 BARE, NOT `{ supported: "…" }`. A noted cell is exempt from the overclaim arm, and the
+  // arm is the point: drop this bundle's text transport and the notice silently stops arriving.
+  "judge-lift-notice": "supported",
+  "name-drop-mention": { unsupported: "not built yet — the ambient supervisor already reads every comment, so a name-drop match adds no wake" },
+  // 🔴 EVERY WAKE LEG ADMITS `created` ONLY, and that is the narrower true claim. The delivery DOES
+  // reach OE code — `wrapRoute` runs the fan-out, the installation leg and the reaction poll on an
+  // edited comment like any other — but no leg that can start a turn admits one: eve's route
+  // dispatches `issue_comment`/`pull_request_review_comment` with `action: "created"`,
+  // `extractGitHubAmbientEvent` reads the same created-only shape, and `parseGitHubStopComment`
+  // agrees.
+  "message-edit-wake": { unsupported: "every wake leg admits `action: \"created\"` only — eve's route, the ambient extractor and the stop leg each refuse an edited comment" },
+  // A review thread on a pull request (§4.6.1).
+  threads: "supported",
+  // A STANDING room (§4.7.1's sense), not §4.5's read_channel container — GitHub has the latter and
+  // `read_channel` is supported below. Every GitHub container is one issue or pull request, so it
+  // exists because somebody filed work and is about that work.
+  rooms: { unsupported: "no standing container — every GitHub container is one issue or pull request" },
+  dm: { unsupported: "no DM plane — GitHub carries no person-to-person message channel" },
+  mpim: { unsupported: "no DM plane — GitHub carries no person-to-person message channel" },
+
+  // --- core verbs (§7.2) -----------------------------------------------------------------------
+  reply: "supported",
+  edit_reply: "supported",
+  react: "supported",
+  no_reply: "supported",
+  read_channel: "supported",
+  read_thread: "supported",
+  // The work-search adapter is CORE-resident and ungated (packages/core/agent/scm/github-search.ts,
+  // `registerCoreWorkSearchAdapter`), not registered from this bundle — but the corpus is GitHub's.
+  search: { supported: "the core-resident adapter (`scm/github-search.ts`), registered ungated" },
+  // NOT a structural absence, and the reason matters: the transport exists (this bundle registers
+  // `SurfaceMessageOps`, and `approvals/chat-post.ts` posts through it). What refuses is the closed
+  // `RESOURCE_TYPES` table in `access/resource-grant.ts`, which carries no row for this surface, so
+  // no `channel` grant can be minted and `chatWriteMount` never arms the tool.
+  post_message: { unsupported: "not built yet — no `channel` row in `access/resource-grant.ts` — OPE-1507" },
+  dm_person: { unsupported: "no DM plane — GitHub carries no person-to-person message channel (§4.7.2)" },
+  set_dm_delivery: { unsupported: "no DM plane — the verb mounts only inside a 1:1 DM (§4.7.2)" },
+  // GitHub sends no webhook for a reaction at all, so the trigger is a comment whose ENTIRE body is
+  // the word `stop` — one thing only, never a magic string competing with real messages (§4.8).
+  stop: { supported: "a comment whose entire body is `stop` — GitHub sends no reaction webhook" },
+  // `react` IS wired, so this is not "no reaction primitive". GitHub's reaction set is the fixed
+  // eight (+1, -1, laugh, confused, heart, hooray, rocket, eyes) and none of them is a raised hand,
+  // so there is no glyph to place — github-message-ops.ts offers no `setReaction` for that reason
+  // rather than faking one against the wrong emoji.
+  ack_stop_glyph: { unsupported: "vendor limit — GitHub's fixed eight reactions carry no raised hand, so there is no ✋ to place" },
+  ack_cancel_note: "supported",
+  stand_down: { supported: "marks the issue/pull-request row; refuses when no row exists" },
+  post_file: { unsupported: "vendor limit — a GitHub comment carries no file-attachment API" },
+};

package/dist/agent/channels/github-catch-up.d.ts

@@ -0,0 +1,29 @@
+import { type NormalizedMessage, type PrFetchFn, type SeatCatchUpFetch } from "@open-everywhere/core/agent/adapter-api.js";
+/** Injected seam so the fetch drives offline in tests; defaults to the package's one read transport. */
+export interface GitHubCatchUpDeps {
+    readonly fetchFn: PrFetchFn;
+    /** Resolve the brokered conversation-read token for a repo. Injected so the fetch drives with no
+     *  credential store; the live default is the same resolver `githubReadAdapter` uses. */
+    readonly resolveToken?: (repoFull: string) => Promise<string>;
+    /** The bot's own login, so its prior comments read as `self` rather than as a foreign bot. Absent ⇒
+     *  the seat's own posts arrive tagged `bot`, which is visible and honest, never a crash. */
+    readonly selfLogin?: string;
+}
+/** The fetch, with its seams exposed so the contract test drives it with no network. */
+export declare function fetchGitHubCatchUpWindow(req: {
+    container: string;
+    sinceMs: number;
+}, deps?: GitHubCatchUpDeps): Promise<readonly NormalizedMessage[]>;
+/**
+ * 🔴 GITHUB STAMPS A COMMENT'S `created_at` TO THE SECOND, and this is the number the shared catch-up
+ * road widens both of its bounds by (OPE-1847, `core/agent/channels/seat-catch-up.ts`
+ * {@link SeatCatchUpDeclaration.timestampPrecisionMs}).
+ * It is the VENDOR'S UNIT, not a margin. Two comments posted inside one wall-clock second — which two
+ * API round trips easily are — come back carrying the SAME instant, so a window that ends strictly at
+ * the trigger's stamp drops the comment the seat woke to read. That is why this leg used to owe a
+ * two-second sleep (`core/scripts/e2e/scenarios.ts`, J-ENGAGED-github).
+ */
+export declare const GITHUB_TIMESTAMP_PRECISION_MS = 1000;
+/** GitHub's registered {@link SeatCatchUpFetch} — the one thing this surface contributes to the shared path. */
+export declare const githubSeatCatchUpFetch: SeatCatchUpFetch;
+//# sourceMappingURL=github-catch-up.d.ts.map

package/dist/agent/channels/github-catch-up.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-catch-up.d.ts","sourceRoot":"","sources":["../../../agent/channels/github-catch-up.ts"],"names":[],"mappings":"AAuBA,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACtB,MAAM,4CAA4C,CAAC;AAkDpD,wGAAwG;AACxG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B;4FACwF;IACxF,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D;gGAC4F;IAC5F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAUD,wFAAwF;AACxF,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC3C,IAAI,GAAE,iBAA4B,GACjC,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAiBvC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,OAAQ,CAAC;AAEnD,gHAAgH;AAChH,eAAO,MAAM,sBAAsB,EAAE,gBAAwG,CAAC"}

package/dist/agent/channels/github-catch-up.js

@@ -0,0 +1,105 @@
+// github-catch-up — GitHub's registered SEAT CATCH-UP FETCH (OPE-1726): the seat's own conversation
+// since its last wake, normalized for core's shared catch-up path (channels/seat-catch-up.ts).
+//
+// WHAT "THE SEAT'S CONTAINER" IS HERE. A GitHub seat is bound to a repo and every wake arrives on ONE
+// issue or pull request, so the history a catch-up owes is that conversation's timeline comments —
+// the same container `read_channel` reads and the same one the reply lands in. The request's
+// `container` is therefore the conversation key `owner/repo#number` the read adapter already mints.
+//
+// WHY A STANDALONE CALLER, not `githubReadAdapter.readChannel`: that method takes a live
+// {@link BindableContext} and runs the turn-time domain-scope fence over it. A catch-up fires from a
+// webhook route with no turn, and its container is the one the wake itself already admitted — the
+// seat is bound to it — so there is no second scope question to ask. The CREDENTIAL is the same
+// brokered conversation-read token the adapter uses, and the transport is the same `getJson` seam,
+// so this read inherits the 429 backoff rather than opening a second, unretried path.
+//
+// `since` IS A VENDOR FILTER, and it is why this leg is cheap: GitHub's issue-comments endpoint takes
+// an ISO timestamp and returns only what changed after it, so a seat that woke a minute ago pays for
+// a near-empty page instead of walking the conversation. The shared path re-applies the same bound on
+// its own side, so a vendor that returned more is trimmed there.
+//
+// An unparseable container yields `[]`. A credential/transport/read error propagates to core's
+// shared seatCatchUp boundary, which keeps the wake alive and records `failed` (OPE-1842).
+import { catchUpSender, resolveConversationReadToken, } from "@open-everywhere/core/agent/adapter-api.js";
+import { getJson, liveGithubReadFetch, parseGithubContainer } from "./github-read.js";
+const API_BASE = "https://api.github.com";
+/** GitHub's page ceiling for the comments endpoint. ONE page: the catch-up window is "since the seat
+ *  last woke", and a conversation that produced more than 100 comments in that window is one the cap
+ *  in core would trim anyway. */
+const CATCH_UP_PAGE_LIMIT = 100;
+/**
+ * Normalize ONE timeline comment, applying the VISIBILITY GATE every fetch adapter owes core: a
+ * comment whose author GitHub does not name is dropped, because an unattributable body must never
+ * reach a seat. An `App`/`Bot` actor is KEPT and tagged `bot` — attributable machine awareness, which
+ * the domain's admission policy then accepts or refuses — and the bot's own login is what lets the
+ * seat recognise its own prior posts as `self`.
+ * Returns undefined for a dropped (unattributed, empty, or undateable) comment.
+ */
+function normalizeComment(c, selfLogin) {
+    const login = c.user?.login;
+    if (!login)
+        return undefined; // unattributable ⇒ fail closed
+    const text = (c.body ?? "").trim();
+    if (text.length === 0)
+        return undefined;
+    const ms = Date.parse(c.created_at ?? "");
+    if (!Number.isFinite(ms))
+        return undefined;
+    const isBot = c.user?.type === "Bot";
+    const isSelf = selfLogin !== undefined && login.toLowerCase() === selfLogin.toLowerCase();
+    return {
+        id: String(c.id ?? `${login}@${c.created_at ?? ms}`),
+        ms,
+        // The bot's OWN posts carry no author id, matching every other surface's normalized shape.
+        ...(isSelf ? {} : { authorId: login }),
+        // THE SHARED SENDER RULE (OPE-1857): this surface contributes the vendor's own signal —
+        // GitHub's `user.type` is `Bot` for an app — and core decides what it means.
+        sender: catchUpSender({ self: isSelf, bot: isBot }),
+        // A timeline comment sits at the top level of its conversation — the same answer
+        // `githubReadAdapter.wakeAddress` gives (only an inline review comment is thread-scoped).
+        type: "channel",
+        text,
+    };
+}
+const liveDeps = {
+    fetchFn: liveGithubReadFetch,
+    // The GitHub App's comment author is `<app-slug>[bot]`; the deployment states its own slug, and an
+    // unset one degrades to "our posts look like a bot's", which the admission policy still admits
+    // under `wide`.
+    selfLogin: process.env.GITHUB_APP_SLUG ? `${process.env.GITHUB_APP_SLUG}[bot]` : undefined,
+};
+/** The fetch, with its seams exposed so the contract test drives it with no network. */
+export async function fetchGitHubCatchUpWindow(req, deps = liveDeps) {
+    const target = parseGithubContainer(req.container);
+    if (!target)
+        return []; // not a conversation key ⇒ nothing addressable to read
+    const token = await (deps.resolveToken ?? resolveConversationReadToken)(target.repoFull);
+    const since = new Date(req.sinceMs).toISOString();
+    const url = `${API_BASE}/repos/${target.repoFull}/issues/${target.number}/comments?per_page=${CATCH_UP_PAGE_LIMIT}&since=${encodeURIComponent(since)}`;
+    const raw = await getJson(deps.fetchFn, url, token, "issues.listComments");
+    // A successful HTTP status with the wrong body shape is an attempted read failure, not evidence
+    // that the conversation was quiet. Keep the error fixed and content-free: the vendor body can
+    // contain arbitrary text and the shared audit row records only the error class/status.
+    if (!Array.isArray(raw))
+        throw new Error("GitHub catch-up returned a malformed response");
+    const out = [];
+    for (const c of raw) {
+        const n = normalizeComment(c, deps.selfLogin);
+        if (n)
+            out.push(n);
+    }
+    return out;
+}
+/**
+ * 🔴 GITHUB STAMPS A COMMENT'S `created_at` TO THE SECOND, and this is the number the shared catch-up
+ * road widens both of its bounds by (OPE-1847, `core/agent/channels/seat-catch-up.ts`
+ * {@link SeatCatchUpDeclaration.timestampPrecisionMs}).
+ * It is the VENDOR'S UNIT, not a margin. Two comments posted inside one wall-clock second — which two
+ * API round trips easily are — come back carrying the SAME instant, so a window that ends strictly at
+ * the trigger's stamp drops the comment the seat woke to read. That is why this leg used to owe a
+ * two-second sleep (`core/scripts/e2e/scenarios.ts`, J-ENGAGED-github).
+ */
+export const GITHUB_TIMESTAMP_PRECISION_MS = 1_000;
+/** GitHub's registered {@link SeatCatchUpFetch} — the one thing this surface contributes to the shared path. */
+export const githubSeatCatchUpFetch = (req) => fetchGitHubCatchUpWindow({ container: req.container, sinceMs: req.sinceMs });
+//# sourceMappingURL=github-catch-up.js.map

package/dist/agent/channels/github-catch-up.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-catch-up.js","sourceRoot":"","sources":["../../../agent/channels/github-catch-up.ts"],"names":[],"mappings":"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"}

package/dist/agent/channels/github-engagement.d.ts

@@ -0,0 +1,223 @@
+import { type EngagementRow, type Partition } from "@open-everywhere/core/agent/adapter-api.js";
+import type { GitHubAmbientAddressing } from "./github-supervisor.js";
+/**
+ * The engagement-registry anchor for one GitHub container, or `undefined` when the delivery names
+ * no container number.
+ *
+ * 🔴 IT IS THE ONE PREDICATE THE MAPPER AND THE SEAM SHARE. `bindGitHub` publishes exactly this as
+ * `engagementKey`, so `stand_down`'s mark and this seam's read address the same row. Two spellings
+ * of "which container this is" is how a stop comes to mark a row no gate reads.
+ */
+export declare function githubEngagementAnchor(owner: string | undefined, repo: string | undefined, num: number | undefined): string | undefined;
+/** The partition one container's engagement row lives in — the REPO grain
+ *  (`github/<owner>/<repo>`), which is what `resolvePartition` gives a bound GitHub session and
+ *  therefore what `stand_down` writes under. It is built from THIS delivery's own facts, through the
+ *  same `buildGitHubAuth` the wake dispatches, so the seam can never key a row the turn would not.
+ *  Null on an unresolvable identity: the caller then keeps today's path, the fail-open posture every
+ *  carriage leg on this surface takes. */
+export declare function githubSeamPartition(f: GitHubSeamFacts): Partition | null;
+/** The facts one comment delivery contributes to the seam. Both legs can build it — the native
+ *  handler from eve's inbound context, the ambient leg from the raw webhook event — so neither
+ *  re-states the policy below. */
+export interface GitHubSeamFacts {
+    readonly owner: string;
+    readonly repo: string;
+    /** The issue or pull-request number the comment landed on. */
+    readonly number: number | undefined;
+    readonly isPrivate?: boolean;
+    /** The comment author's login — the principal this delivery binds. It rides the facts rather than
+     *  being stubbed here so the partition the seam keys is built from the delivery's own identity. */
+    readonly actorLogin: string;
+    /** The comment @mentions this deployment's app (the caller's own `githubBotMentioned` verdict). */
+    readonly isMention: boolean;
+    /** The comment was written by a bot or by this app itself — never delivered (loop guard). */
+    readonly authorIsBot: boolean;
+    /** The container this comment landed in, in GitHub's own vocabulary — `issue`, `pull_request` or
+     *  `review_thread`. The seam reads it for one question, in
+     *  {@link githubEngagedFollowUpReach}: an INLINE review comment shares its pull request's anchor,
+     *  so a review thread is not a container of its own. Required rather than optional, because a
+     *  caller that forgets it would silently widen that arm. */
+    readonly conversationKind: string | undefined;
+}
+/**
+ * May the NON-MENTION arm of the seam reach this delivery at all? Read BEFORE any registry read, by
+ * both legs, so the two never disagree about which comments the native leg owns.
+ *
+ * TWO FLOORS. Each refuses on an unknown rather than admitting, and each is about REACH — whether
+ * this kind of delivery may wake at all — never about whether the container is engaged.
+ *
+ *  • 🔴 THE REPO MUST BE POSITIVELY PRIVATE. An engaged container's plain comment wakes a FULL
+ *    native turn: a sandbox checkout and a judged spend. On a public repo that lets ANY GitHub
+ *    account buy one, by writing in an issue somebody once @mentioned the app in — the same
+ *    drive-by spend and prompt-injection surface `classifyGitHubAmbientComment` step 5 refuses for,
+ *    on the louder of the two legs. 🔴 THIS FLOOR IS STRICTER THAN THAT ONE, deliberately: step 5
+ *    admits a VOUCHED public repo, and this one refuses every public repo. A vouch widens the
+ *    ambient supervisor's judged reply; widening an uninvited NATIVE turn to a public repo is a
+ *    bigger step that needs its own ruling.
+ *  • 🔴 A REVIEW THREAD IS NOT A CONTAINER OF ITS OWN. {@link githubEngagementAnchor} collapses to
+ *    `owner/repo#N`, so every INLINE review comment on a pull request reads the row that one
+ *    @mention anywhere on that pull request engaged — and one review leaves dozens of them.
+ *
+ * AN @MENTION IS UNAFFECTED BY BOTH, on a public repo and inside a review thread alike: it is
+ * answered by the caller's own mention gate, which this seam never narrows.
+ */
+export declare function githubEngagedFollowUpReach(f: GitHubSeamFacts): {
+    readonly reachable: boolean;
+    readonly reason: string;
+};
+/**
+ * What the seam says about one inbound comment. Four outcomes, each naming what the CALLER owes:
+ *
+ *  • `unanchored` — the delivery names no container, so there is no row to address and the caller
+ *    keeps today's path exactly.
+ *  • `engage` — an @mention. The caller marks the container engaged ({@link markGitHubEngaged}); the
+ *    mention itself is answered by the caller's own path, never by the seam.
+ *  • `deliver` — a plain comment in an engaged container. The caller wakes a turn.
+ *  • `hold` — a plain comment the seam does not admit. `stopped` says WHY, and it is the one field a
+ *    caller must branch on: `stopped: true` means the agent was asked to stand down in this
+ *    container, so the comment must be SUPPRESSED outright — including on the ambient leg, which
+ *    does not otherwise read this registry. `stopped: false` means the container simply is not
+ *    engaged, which is not a suppression: the caller keeps today's path.
+ */
+export type GitHubEngagementVerdict = {
+    readonly kind: "unanchored";
+    readonly reason: string;
+} | {
+    readonly kind: "engage";
+    readonly anchor: string;
+} | {
+    readonly kind: "deliver";
+    readonly anchor: string;
+    readonly reason: string;
+} | {
+    readonly kind: "hold";
+    readonly anchor: string;
+    readonly reason: string;
+    readonly stopped: boolean;
+};
+/** Injectable seams so the whole verdict is unit-tested without a store. */
+export interface GitHubEngagementDeps {
+    readonly getEngagement?: (p: Partition, anchor: string) => Promise<EngagementRow | null>;
+    readonly markEngaged?: (p: Partition, anchor: string, atIso: string) => Promise<void>;
+    /** The mark's durable once-guard — see {@link markGitHubEngaged}. Injected so a test can drive a
+     *  redelivered @mention without an operational store. */
+    readonly markEventSeen?: (org: string, key: string, atIso: string) => Promise<boolean>;
+    readonly now?: () => string;
+}
+/**
+ * Resolve the seam for one comment — READ-ONLY. The mark is a separate call
+ * ({@link markGitHubEngaged}) so exactly one caller writes the row: two writers is how one comment
+ * comes to engage a container twice, once on each leg.
+ *
+ * ORDERING. A mention is settled before any read: it is always answered by the caller's own path, so
+ * its verdict costs no store round-trip. Only a plain comment pays for a read, and it pays for
+ * exactly one — the ROW, not a boolean, because the row carries both facts the decision needs (is
+ * this engaged, and was the agent asked to stand down here) and two reads could disagree.
+ *
+ * THE DECISION ITSELF IS CORE'S. `shouldDeliverReply` owns the disqualifier order and the reasons;
+ * this function only translates GitHub facts into its input. Nothing here re-states the policy.
+ *
+ * FAIL-CLOSED on a store error: `getThreadEngagement` reads a failure as `null`, so an unreadable
+ * registry holds rather than delivers — the agent does not barge into a conversation it cannot prove
+ * it was invited to.
+ */
+export declare function resolveGitHubEngagement(f: GitHubSeamFacts, deps?: GitHubEngagementDeps): Promise<GitHubEngagementVerdict>;
+/**
+ * Mark one container ENGAGED on an @mention, ONCE PER COMMENT.
+ *
+ * `participating: true` is the re-invitation: it promotes the row and CLEARS a previous stand-down,
+ * which is what "an @mention brings the agent back" means on every surface that wires this seam.
+ *
+ * 🔴 THE MARK IS DEDUPED, AND THE STOP IS WHY. Clearing the flag is right for a person's second
+ * @mention and WRONG for GitHub redelivering the first one — a redelivered webhook would quietly
+ * lift a stand-down nobody asked to lift. `commentId` is the comment's own id, so the guard keys on
+ * the thing that must happen once. It is the DURABLE layer only, unlike Teams' front: this route
+ * holds no in-process dedupe object, and a serverless invocation is a fresh process, so an
+ * in-memory layer would catch almost nothing here. FAIL-OPEN on a store error, the same posture
+ * every dedupe in this repository takes — a dedupe prevents a double write, not a security hole.
+ *
+ * Best-effort throughout — `markThreadEngaged` swallows a store failure, because engagement
+ * bookkeeping must never fail a turn. Returns the anchor it marked, or null when it marked nothing.
+ */
+export declare function markGitHubEngaged(f: GitHubSeamFacts, commentId: string | number | undefined, deps?: GitHubEngagementDeps): Promise<string | null>;
+/**
+ * Is this comment MACHINE-AUTHORED — a GitHub App, a bot account, or this deployment's own reply?
+ *
+ * 🔴 ONE PREDICATE, AND IT MUST FAIL CLOSED ON AN UNRESOLVED SLUG. `githubBotMentioned` needs the
+ * app slug to recognise a mention at all, so before this seam a deployment with no `GITHUB_APP_SLUG`
+ * simply never woke natively. A plain comment now reaches the seam, and without the slug the app
+ * cannot tell its OWN reply from a person's — so "unknown" answers `true` and nothing is delivered,
+ * the same posture `classifyGitHubAmbientComment` takes with its own no-slug drop.
+ */
+export declare function githubMachineAuthored(authorLogin: string | undefined, authorType: string | undefined, botSlug: string | undefined): boolean;
+/**
+ * The NATIVE leg's one-line admission (`github.ts`'s mention gate): may this plain, non-mention
+ * comment run a turn?
+ *
+ * It exists because the native channel is where a GitHub turn is minted — the wake is the webhook
+ * itself, so admitting the comment through the mention gate IS the wake. The ambient leg owns the
+ * complementary halves above it (the STOP suppression, and dropping a comment this leg now owns), so
+ * this call only ever answers the delivery question, and it never writes.
+ *
+ * 🔴 THE REACH FLOORS RUN FIRST, above the registry read: a public repo and an inline review comment
+ * are refused whatever the row says ({@link githubEngagedFollowUpReach}). Putting them here rather
+ * than in {@link resolveGitHubEngagement} is deliberate — the ambient leg reads that function for the
+ * STOP, and a stood-down container must stay suppressed on a public repo too.
+ */
+export declare function githubEngagedAdmits(f: GitHubSeamFacts, deps?: GitHubEngagementDeps): Promise<boolean>;
+/**
+ * WHAT WOKE ONE AMBIENT-LEG DELIVERY, for the `github.dispatched` audit row (OPE-1752).
+ *
+ * 🔴 THE CLASSIFIER'S OWN WORD CANNOT ANSWER THIS, AND WRITING IT WAS THE DEFECT.
+ * `classifyGitHubAmbientComment` answers a narrower question — did this comment ADDRESS the agent —
+ * and an engaged follow-up did not, so it stays `channel-watch`. That is the right answer to its own
+ * question, and `channel-watch` is what makes the turn a JUDGED one. But `channel-watch` ALSO names
+ * unowned chatter in an un-enrolled issue, and the audit row is the one place those two must not
+ * read alike. This is the same promotion OPE-1510 made on Notion (`notionWakeAddressing`) and
+ * OPE-1578 made on Linear (`linearWakeAddressing`) — one concept, one spelling, across three
+ * surfaces.
+ *
+ * 🔴 THE MAPPING IS THE ROW'S ALONE, and nothing else has to be re-derived from it. The classifier's
+ * value reaches five places in `github.ts`, and TWO of them are behavioural: the `drop` return, the
+ * `githubAmbientLegAdmission` gate input, the seam facts' `isMention`, `directMention` — which is
+ * what the wake envelope and `singleWindowMentionPolicy` are built from — and this row. The gate
+ * input and `directMention` are the behavioural two, and NEITHER reads the PROMOTED value: both take
+ * the classifier's word directly, above this mapping. `github-supervisor.ts` derives the wake
+ * envelope's own `addressing`
+ * from `directMention` (`directMention ? "direct-mention" : "channel-watch"`), and the
+ * unified-window wake takes `singleWindowMentionPolicy(singleWindow, directMention, vouched)`.
+ * Neither reads this value. So the turn is judged the same, and the SILENCE BAR is what it always
+ * was, whatever this function returns.
+ *
+ * 🔴 A ROW THAT CANNOT TELL THEM APART REDS `J-ENGAGED-github` STEP (b) AGAINST A HEALTHY
+ * DEPLOYMENT. `gateEngagedWake` (packages/core/scripts/e2e/scenarios.ts) skips on an EMPTY dispatch
+ * read only, so a non-empty read carrying `channel-watch` is a hard gate failure, not an ignored
+ * value. Measured on deploy #203: the follow-up woke, dispatched and was ANSWERED (`reply.post`,
+ * 2026-09-12T20:27:25Z), and only the label disagreed. What the promotion DOES oblige is every
+ * reader that filtered the ambient leg by the literal `"channel-watch"` — `AMBIENT_LEG_ADDRESSINGS`
+ * (packages/core/scripts/e2e/engaged-rows.ts) is the pair such a reader takes.
+ *
+ * 🔴 IT REPORTS THE ENGAGED DOOR, AND THAT DOOR CARRIES A REACH FLOOR LINEAR'S DOES NOT. Linear's
+ * input is the bare seam verdict; GitHub's is `admission.engagedFollowUp`, which is
+ * `seam.kind === "deliver" && githubEngagedFollowUpReach(f).reachable`. So the promotion needs BOTH
+ * an enrolled container and a reachable one, and {@link githubEngagedFollowUpReach} refuses a public
+ * or unknown-privacy repo and an inline review comment. An engaged issue on a VOUCHED PUBLIC repo
+ * with ambient ON therefore still writes `channel-watch`: the classifier keeps that comment, but the
+ * engaged door is shut and the native leg would not have woken a turn for it either. That is the
+ * right answer — the row reports the door the delivery actually came through — and it is a narrower
+ * claim than Linear's, so do not read the two mappings as identical in reach.
+ *
+ * 🔴 IT REPORTS THE REGISTRY, NOT THE AMBIENT OPT-IN. `githubAmbientLegAdmission` resolves the seam
+ * for every kept comment, ABOVE the `githubAmbientEnabled` gate and independently of it, so on an
+ * ambient-ENABLED private repo an engaged issue's plain comment also reads `thread-follow` — the
+ * opt-in would have admitted it either way. The value therefore separates an engaged wake from an
+ * ambient one only where the domain has ambient OFF, which is the addressed-only posture the
+ * journeys drive.
+ *
+ * `engagedFollowUp` is the caller's own admission verdict, and it is the only door a plain comment
+ * has on a repo that never opted in. The `channel-watch` guard is belt-and-braces:
+ * `drop` returns before the row is written and can never reach here, and `direct` is an address
+ * rather than a follow-up.
+ */
+export declare function githubWakeAddressing(addressing: GitHubAmbientAddressing, engagedFollowUp: boolean | undefined): GitHubAmbientAddressing | "thread-follow";
+//# sourceMappingURL=github-engagement.d.ts.map

package/dist/agent/channels/github-engagement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-engagement.d.ts","sourceRoot":"","sources":["../../../agent/channels/github-engagement.ts"],"names":[],"mappings":"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"}