@kya-os/cli 1.7.0 → 1.8.3

package/dist/orchestrator/db/verdicts.js

@@ -0,0 +1,197 @@
+/**
+ * Verdict and quorum store.
+ *
+ * The point of this module is that both writes are idempotent by NATURAL key,
+ * not by a hash of the event that produced them:
+ *
+ *   - a verdict is unique per (repo, pr, head_sha, reviewer_did)
+ *   - quorum is unique per (repo, pr, head_sha)
+ *
+ * Those keys are what the review protocol already means, so "have we processed
+ * this?" is answered by asking whether the row exists. The previous approach
+ * derived a content hash of the hub event and stored a synthetic marker beside
+ * the ticket, which needed its own scoping, its own lookup path, and its own
+ * durability guarantees -- three review findings' worth of them. A UNIQUE
+ * constraint the schema already declared does the same job and cannot expire,
+ * collide across tickets, or be looked for in the wrong window.
+ *
+ * `verdicts` was in the schema from the start with exactly this shape and no
+ * reader; this is that reader.
+ *
+ * @module cli/orchestrator/db/verdicts
+ */
+import { z } from "zod";
+export const VerdictKindSchema = z.enum(["approve", "request-changes", "comment"]);
+export const VerdictRowSchema = z.object({
+    id: z.string(),
+    ticket_id: z.string().nullable(),
+    repo: z.string(),
+    pr_number: z.number(),
+    head_sha: z.string(),
+    reviewer_did: z.string(),
+    verdict: VerdictKindSchema,
+    findings: z.string().nullable(),
+    counted: z.number(),
+    received_at: z.string(),
+});
+/**
+ * Record one reviewer's verdict on one head SHA.
+ *
+ * Returns true when something CHANGED: the verdict is new, or the same reviewer
+ * revised it on the same head. False means this exact verdict was already
+ * recorded, which is a replay, a re-delivered event, or a boot reconcile of a
+ * window already processed.
+ *
+ * `received_at` is NEVER rewritten on conflict: it is the FIRST sighting of this
+ * head, which head ranking depends on, and letting a late revision move it
+ * contradicted the very function that reads it. A revision updates the verdict,
+ * not when the head was first seen.
+ *
+ * The mind-change case is why this is an upsert rather than INSERT OR IGNORE.
+ * The hub explicitly permits a reviewer to follow an approval with
+ * request-changes on the SAME head and emits a second review_verdict for it. On
+ * a plain OR IGNORE that second verdict is dropped as "already handled" and the
+ * ticket never goes back to in-progress -- a reviewer withdrawing approval would
+ * be silently overruled by a uniqueness constraint.
+ *
+ * The guarded UPDATE is what keeps false meaning "nothing to do": re-delivering
+ * an identical verdict fails the WHERE, changes no rows, and reports false.
+ * `findings` is part of that comparison so a revision that only changes its
+ * reasons is still stored -- otherwise the recorded findings silently went stale
+ * while the verdict itself looked current.
+ *
+ * The id is a readable composite of the natural key rather than a hash, so a row
+ * can be found by hand in a debugging session.
+ */
+export function recordVerdict(db, input) {
+    const id = `${input.repo}#${input.prNumber}#${input.headSha}#${input.reviewerDid}`;
+    const info = db
+        .prepare(`INSERT INTO verdicts
+         (id, ticket_id, repo, pr_number, head_sha, reviewer_did, verdict, findings, counted, received_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(repo, pr_number, head_sha, reviewer_did) DO UPDATE SET
+         verdict     = excluded.verdict,
+         findings    = excluded.findings,
+         counted     = excluded.counted,
+         ticket_id   = excluded.ticket_id
+       WHERE verdicts.verdict IS NOT excluded.verdict
+          OR verdicts.counted IS NOT excluded.counted
+          OR verdicts.findings IS NOT excluded.findings`)
+        .run(id, input.ticketId, input.repo, input.prNumber, input.headSha, input.reviewerDid, input.verdict, input.findings === undefined ? null : JSON.stringify(input.findings), input.counted ? 1 : 0, new Date(input.observedAt).toISOString());
+    return info.changes > 0;
+}
+/**
+ * Record that the hub declared quorum on one head SHA.
+ *
+ * Returns true when it was new. Quorum is stored rather than recomputed because
+ * the hub owns verdict validation, and a second implementation of the threshold
+ * here could disagree with the one that actually gated the decision.
+ */
+export function recordQuorum(db, input) {
+    const info = db
+        .prepare(`INSERT OR IGNORE INTO pr_quorum (repo, pr_number, head_sha, ticket_id, quorum_n, reached_at)
+       VALUES (?, ?, ?, ?, ?, ?)`)
+        .run(input.repo, input.prNumber, input.headSha, input.ticketId, input.quorumN ?? null, new Date(input.observedAt).toISOString());
+    return info.changes > 0;
+}
+/** Every verdict on one PR head, newest first. */
+export function listVerdictsForPr(db, repo, prNumber, headSha) {
+    const rows = headSha
+        ? db
+            .prepare(`SELECT * FROM verdicts WHERE repo = ? AND pr_number = ? AND head_sha = ?
+             ORDER BY received_at DESC, id`)
+            .all(repo, prNumber, headSha)
+        : db
+            .prepare(`SELECT * FROM verdicts WHERE repo = ? AND pr_number = ? ORDER BY received_at DESC, id`)
+            .all(repo, prNumber);
+    return z.array(VerdictRowSchema).parse(rows);
+}
+/** Has the hub already declared quorum on this head? */
+export function quorumReached(db, repo, prNumber, headSha) {
+    return (db
+        .prepare(`SELECT 1 FROM pr_quorum WHERE repo = ? AND pr_number = ? AND head_sha = ?`)
+        .get(repo, prNumber, headSha) !== undefined);
+}
+/**
+ * The most recently seen head SHA for a pull request.
+ *
+ * Which revision the ledger currently believes is live. A push invalidates every
+ * prior verdict (the review protocol's settled rule), so status has to be derived
+ * from the newest head rather than from whichever head the event in hand names --
+ * otherwise a late or replayed quorum for superseded code moves current work.
+ * `counted: false` marks a stale VERDICT; quorum has no such flag.
+ *
+ * Ranked by when each head was FIRST seen, not when it was last touched. This is
+ * the whole correctness of the function. Ranking by last-touched let any newly
+ * recorded row for an older SHA promote it to "latest" -- including an uncounted
+ * stale verdict kept purely as evidence. Historical quorum on that superseded
+ * head would then clear a live objection on the real one, defeating the
+ * uncounted guard this derivation depends on. A head's first sighting cannot be
+ * moved by a late arrival, because the upsert never rewrites `received_at`.
+ *
+ * "When" is PROTOCOL time -- the hub event's own timestamp, carried in on
+ * `observedAt` -- not the wall clock at insert. Insert time made this a coin
+ * flip in the one case that matters most: on a cold start, `reconcileReviewState`
+ * replays the window fast enough that consecutive better-sqlite3 inserts land in
+ * the same millisecond, so every head tied and the winner fell to the SHA
+ * tiebreak. Half the time that elected the OLD head, derived a historical quorum
+ * against it, and moved a ticket to `ready` straight past a live counted
+ * request-changes on the new one.
+ *
+ * Ties still break on head_sha, for genuinely simultaneous protocol timestamps:
+ * an arbitrary-but-stable answer beats a fresh coin flip per query, and truly
+ * simultaneous revisions are ambiguous under any rule.
+ */
+export function latestHeadForPr(db, repo, prNumber) {
+    const row = db
+        .prepare(`SELECT head_sha FROM (
+         SELECT head_sha, MIN(at) AS first_seen FROM (
+           SELECT head_sha, received_at AS at FROM verdicts  WHERE repo = ? AND pr_number = ?
+           UNION ALL
+           SELECT head_sha, reached_at  AS at FROM pr_quorum WHERE repo = ? AND pr_number = ?
+         )
+         GROUP BY head_sha
+       ) ORDER BY first_seen DESC, head_sha DESC LIMIT 1`)
+        .get(repo, prNumber, repo, prNumber);
+    if (row === undefined || row === null)
+        return undefined;
+    return z.object({ head_sha: z.string() }).parse(row).head_sha;
+}
+/**
+ * The same ranking as {@link latestHeadForPr}, blind to uncounted verdicts.
+ *
+ * `latestHeadForPr` deliberately ranks EVERY verdict, counted or not -- a
+ * verdict naming a stale or malformed SHA still proves the hub saw that SHA,
+ * which is what that function's contract promises. But "a SHA was mentioned"
+ * and "a SHA was genuinely reviewed" are different questions, and DERIVING
+ * status needs the second one: a verdict the hub itself flagged invalid must
+ * not be able to outrank a real counted verdict or quorum recorded on a
+ * different head just because it happened to arrive with a later protocol
+ * timestamp. Left unfiltered, that lets review noise on a throwaway SHA
+ * occlude a real objection sitting under the head that actually matters --
+ * the ticket keeps whatever status the occluded head implied, forever,
+ * because nothing ever asks about that head again.
+ *
+ * Quorum rows carry no `counted` column and are never filtered here, the same
+ * way {@link latestHeadForPr} treats them: the hub is the sole authority for
+ * quorum, so a recorded quorum is trusted unconditionally.
+ *
+ * Returns undefined when no head has ANY trusted evidence yet -- distinct
+ * from "no evidence at all," which only {@link latestHeadForPr} can answer.
+ */
+export function latestTrustedHeadForPr(db, repo, prNumber) {
+    const row = db
+        .prepare(`SELECT head_sha FROM (
+         SELECT head_sha, MIN(at) AS first_seen FROM (
+           SELECT head_sha, received_at AS at FROM verdicts  WHERE repo = ? AND pr_number = ? AND counted = 1
+           UNION ALL
+           SELECT head_sha, reached_at  AS at FROM pr_quorum WHERE repo = ? AND pr_number = ?
+         )
+         GROUP BY head_sha
+       ) ORDER BY first_seen DESC, head_sha DESC LIMIT 1`)
+        .get(repo, prNumber, repo, prNumber);
+    if (row === undefined || row === null)
+        return undefined;
+    return z.object({ head_sha: z.string() }).parse(row).head_sha;
+}
+//# sourceMappingURL=verdicts.js.map

package/dist/orchestrator/db/verdicts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdicts.js","sourceRoot":"","sources":["../../../src/orchestrator/db/verdicts.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/events.d.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+/**
+ * The slice of the coordination hub this package consumes (ORC-W1 PR-2).
+ *
+ * Declared structurally rather than imported from `@kya-os/compute`, matching
+ * how `review-coordinator.ts` declares `DispatchHub` in that same package and
+ * for the same reason: tests drive a lightweight fake instead of standing up a
+ * real hub, and the orchestrator stays decoupled from where the hub runs. It
+ * can be embedded locally today and remote later without this package moving.
+ *
+ * @module orchestrator/events
+ */
+/**
+ * A hub event as observed by the daemon.
+ *
+ * `type` is a bare `string`, deliberately NOT the hub's union. The union
+ * widens over time (`review_verdict` and `pr_quorum_reached` arrived with
+ * xmcp-i#661) and this package must persist an event type it has never been
+ * taught rather than drop it. Narrowing here would mean a hub release could
+ * silently cost the ledger exactly the events worth having, and ORC-W3
+ * depends on that not happening.
+ */
+export interface HubEventLike {
+    type: string;
+    timestamp: number;
+    agentDid: string;
+    agentName: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Runtime shape check for a frame claiming to be a {@link HubEventLike}.
+ *
+ * `type` stays `z.string().min(1)` rather than an enum, for the identical
+ * reason the interface above does: the hub's event union widens over time and
+ * this must keep persisting a type it has never been taught. What this DOES
+ * reject is a frame missing the fields every event actually carries -- the gap
+ * an unchecked `as HubEventLike` cast over a WebSocket leaves wide open, since
+ * nothing on the wire guarantees the hub (or anything speaking its protocol)
+ * sent a well-formed frame.
+ */
+export declare const HubEventLikeSchema: z.ZodObject<{
+    type: z.ZodString;
+    timestamp: z.ZodNumber;
+    agentDid: z.ZodString;
+    agentName: z.ZodString;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    data: Record<string, unknown>;
+    type: string;
+    timestamp: number;
+    agentDid: string;
+    agentName: string;
+}, {
+    data: Record<string, unknown>;
+    type: string;
+    timestamp: number;
+    agentDid: string;
+    agentName: string;
+}>;
+/** Subscription surface. `onEvent` returns its own unsubscribe, as the hub's does. */
+export interface EventSource {
+    onEvent(handler: (event: HubEventLike) => void): () => void;
+    /**
+     * Recent events, used once on boot to reconcile what the daemon slept
+     * through. The hub's own signature defaults to 50.
+     */
+    getRecentEvents(limit?: number): HubEventLike[];
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/orchestrator/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/orchestrator/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;EAM7B,CAAC;AAEH,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5D;;;OAGG;IACH,eAAe,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;CACjD"}

package/dist/orchestrator/events.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+/**
+ * Runtime shape check for a frame claiming to be a {@link HubEventLike}.
+ *
+ * `type` stays `z.string().min(1)` rather than an enum, for the identical
+ * reason the interface above does: the hub's event union widens over time and
+ * this must keep persisting a type it has never been taught. What this DOES
+ * reject is a frame missing the fields every event actually carries -- the gap
+ * an unchecked `as HubEventLike` cast over a WebSocket leaves wide open, since
+ * nothing on the wire guarantees the hub (or anything speaking its protocol)
+ * sent a well-formed frame.
+ */
+export const HubEventLikeSchema = z.object({
+    type: z.string().min(1),
+    timestamp: z.number(),
+    agentDid: z.string(),
+    agentName: z.string(),
+    data: z.record(z.string(), z.unknown()),
+});
+//# sourceMappingURL=events.js.map

package/dist/orchestrator/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/orchestrator/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgCxB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;CACxC,CAAC,CAAC"}

package/dist/orchestrator/github-credential-anchor-sender.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Anchoring a GitHub credential in the hub (review-loop P16, commit 3).
+ *
+ * Builds a signed `GithubCredentialAnchor` (see `@kya-os/contracts/handshake/
+ * github-credential-anchor.ts`) from a locally stored credential
+ * (`utils/github-credential.ts`) and delivers it to the configured hub over
+ * the SAME observer wire path `hub-observer.ts` speaks: `observe` hello,
+ * challenge, proof-of-possession -- see that file's module doc for why this
+ * package never imports `@kya-os/compute` and instead speaks the shared
+ * wire format directly. Unlike `HubObserver`, this is a ONE-SHOT
+ * connect/authenticate/submit/await-result/close, not a long-lived
+ * reconnecting subscription -- a different lifecycle for a different job,
+ * so it does not extend or wrap that class.
+ *
+ * The anchor is signed and the wire connection authenticated with the SAME
+ * key: the designated agent profile's signing key
+ * (`signingKeyPath(agentSlug)`, the exact file `dco setup`/`dco fix` already
+ * use -- see `ssh-key.ts`'s `parseEd25519SshPrivateKeyPem`). That is what
+ * lets the hub check "the anchor's proof verifies against the DID that
+ * authenticated this very connection" without a second key or a fresh
+ * resolution: the hub already knows this socket proved control of `did`
+ * before a single `credential_anchor` frame arrives.
+ *
+ * No hub configured, or the hub unreachable: the anchor is queued at
+ * `~/.mcpi/github/pending-anchor.json` (fingerprints and proof only -- by
+ * construction, since `GithubCredentialAnchorSchema` holds no secret) for a
+ * later `kya-os init` or P17's wrapper connection to deliver.
+ *
+ * @module cli/orchestrator/github-credential-anchor-sender
+ */
+import WebSocket from "ws";
+import { type GithubCredentialAnchor } from "@kya-os/contracts/handshake";
+import { type ObserverIdentity } from "./hub-observer.js";
+import { type StoredGithubCredential } from "../utils/github-credential.js";
+export interface BuildGithubCredentialAnchorParams {
+    /** The profile signing this anchor -- its DID goes on the wire; its slug locates `signingKeyPath`. */
+    agentDid: string;
+    agentSlug: string;
+    /** All profile DIDs authorized to use this credential, including the signer's. */
+    agentDids: string[];
+    /** Prior anchor's tokenFingerprint, when this anchor rotates one out. */
+    supersedes?: string;
+    now?: () => string;
+    /** Reads the profile's converted signing key PEM. Injectable for tests. */
+    readSigningKeyPemImpl?: (agentSlug: string) => string;
+}
+export interface BuiltGithubCredentialAnchor {
+    anchor: GithubCredentialAnchor;
+    /**
+     * The SAME key that signed the anchor, reused to authenticate the wire
+     * connection that delivers it (see the module doc for why one key does
+     * both jobs). Never anything but this key's DID + seed -- no secret from
+     * `credential` is ever in reach of this value.
+     */
+    identity: ObserverIdentity;
+}
+/**
+ * Derive the `ObserverIdentity` (did + raw Ed25519 seed) an agent profile
+ * signs and authenticates with, from its converted signing key file
+ * (`signingKeyPath(agentSlug)`, the same file `dco setup`/`dco fix` use).
+ * Shared by {@link buildGithubCredentialAnchor} (a fresh anchor's signer)
+ * and `github-credential-stage.ts` (re-authenticating to deliver a
+ * previously queued anchor, where no new anchor is being built) so both
+ * paths derive the SAME identity for the same profile from one place.
+ */
+export declare function identityForAgentProfile(agentDid: string, agentSlug: string, readSigningKeyPemImpl?: (agentSlug: string) => string): ObserverIdentity;
+/**
+ * Build and sign a `GithubCredentialAnchor` for `credential`. Signing stays
+ * entirely inside this module -- callers never touch key material, only the
+ * finished anchor and the identity derived alongside it (matching how
+ * `dco fix.ts` keeps its Ed25519 seed scoped to one function, extended here
+ * to the one extra byproduct -- the wire identity -- that a second read of
+ * the same file would otherwise require).
+ */
+export declare function buildGithubCredentialAnchor(credential: Pick<StoredGithubCredential, "githubLogin" | "token" | "webhookSecret" | "scopes">, fingerprints: {
+    tokenFingerprint: string;
+    webhookSecretFingerprint: string;
+}, params: BuildGithubCredentialAnchorParams): BuiltGithubCredentialAnchor;
+export type SendGithubCredentialAnchorResult = {
+    delivered: true;
+} | {
+    delivered: false;
+    reason: string;
+};
+export interface SendGithubCredentialAnchorOptions {
+    endpoint: string;
+    identity: ObserverIdentity;
+    /** Ms to wait for the whole exchange (connect through result). Default 10s. */
+    timeoutMs?: number;
+    /** DI seam for tests -- default `new WebSocket(endpoint)`. */
+    wsFactory?: (endpoint: string) => WebSocket;
+}
+/**
+ * Connect to the hub as an authenticated observer, submit `anchor` once
+ * admitted, and resolve with whether the hub accepted it. Always settles
+ * (never hangs): a timeout, a socket error, or an early close all resolve
+ * `{ delivered: false, reason }` rather than rejecting -- the caller's
+ * fallback is "queue it locally," not "crash the init stage."
+ */
+export declare function sendGithubCredentialAnchor(anchor: GithubCredentialAnchor, options: SendGithubCredentialAnchorOptions): Promise<SendGithubCredentialAnchorResult>;
+/** ~/.mcpi/github/pending-anchor.json -- fingerprints and proof only; no secrets by construction. */
+export declare function pendingAnchorPath(): string;
+/**
+ * A queued anchor, plus the DID of the profile that actually SIGNED it.
+ * Retrying delivery must re-authenticate as exactly that DID -- the hub
+ * checks the anchor's proof against the wire connection's own key, so
+ * anything else fails verification. `agentDids` (on the anchor itself)
+ * lists every profile AUTHORIZED to use the credential, not which one
+ * signed this particular anchor, so the signer has to be recorded
+ * separately rather than assumed from array position.
+ */
+export interface PendingGithubCredentialAnchor {
+    anchor: GithubCredentialAnchor;
+    signerDid: string;
+}
+/** The queued anchor and its signer, or undefined if none is pending (or the file is unreadable/corrupt). */
+export declare function readPendingAnchor(): PendingGithubCredentialAnchor | undefined;
+export declare function clearPendingAnchor(): void;
+export type DeliverGithubCredentialAnchorResult = {
+    status: "delivered";
+} | {
+    status: "pending";
+    reason: string;
+};
+export interface DeliverGithubCredentialAnchorOptions {
+    /** undefined means "not configured" -- resolved by the caller from --hub / DIDCOMM_HUB_ENDPOINT. */
+    hubEndpoint?: string;
+    sendImpl?: typeof sendGithubCredentialAnchor;
+    onNotice?: (message: string) => void;
+}
+/**
+ * Deliver `anchor` to the hub if one is configured and reachable; otherwise
+ * queue it at {@link pendingAnchorPath} and exit cleanly. Never throws --
+ * every failure mode degrades to "pending," which is exactly the offline
+ * path the init stage needs to complete without a hub.
+ */
+export declare function deliverGithubCredentialAnchor(anchor: GithubCredentialAnchor, identity: ObserverIdentity, options?: DeliverGithubCredentialAnchorOptions): Promise<DeliverGithubCredentialAnchorResult>;
+/**
+ * Attempt delivery of a previously queued anchor (e.g. from a later
+ * `kya-os init`, or P17's wrapper connection). A no-op, reported distinctly,
+ * when nothing is queued.
+ *
+ * `resolveIdentity` maps the queued anchor's recorded `signerDid` to that
+ * profile's CURRENT identity -- never a caller-guessed one. `listProfiles()`
+ * has no defined order (`readdirSync`), so "the first profile on the
+ * machine" today is not reliably the profile that signed a PRIOR anchor;
+ * looking it up by the DID actually recorded at queue time is what makes
+ * this retry succeed instead of failing proof verification against the
+ * wrong key. Never throws, matching every other function in this module's
+ * "degrade to pending" contract: `resolveIdentity` typically ends up
+ * calling {@link identityForAgentProfile}, which reads a signing key file
+ * off disk and throws if it's missing or unreadable -- a real possibility
+ * (deleted, corrupted, permissions) that must fall through to "pending"
+ * exactly like a resolved-but-unusable identity, not crash the caller.
+ */
+export declare function deliverPendingGithubCredentialAnchor(resolveIdentity: (signerDid: string) => ObserverIdentity | undefined, options?: DeliverGithubCredentialAnchorOptions): Promise<DeliverGithubCredentialAnchorResult | {
+    status: "none";
+}>;
+//# sourceMappingURL=github-credential-anchor-sender.d.ts.map

package/dist/orchestrator/github-credential-anchor-sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-credential-anchor-sender.d.ts","sourceRoot":"","sources":["../../src/orchestrator/github-credential-anchor-sender.ts"],"names":[],"mappings":"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"}