pm-github 2026.10.19 → 2026.10.23

package/dist/index.js

@@ -14,14 +14,19 @@
 // Issues use the REST API; Projects v2 is GraphQL-only (see the Projects v2
 // section below and the pure plan/mapping logic in ./projects.ts).
 import { CloseoutUsageError, compactCloseoutReport, runCloseout } from "./closeout.js";
-import { buildImportFidelity, fetchImportTimeline, matchImportedIssue, persistImportFidelity, readImportReleases, selectImportContextIndex, } from "./import-fidelity.js";
+import { AmbiguousCitationError, buildImportFidelity, fetchImportTimeline, importFidelityFields, matchImportedIssue, persistImportFidelity, readImportReleases, selectImportContextIndex, validateImportLifetime, } from "./import-fidelity.js";
+import { refreshChanges, runRefresh } from "./refresh.js";
+import { exploreGithubIdentities, planGithubIdentityRepair, applyGithubIdentityRepair } from "./identity.js";
+export { exploreGithubIdentities, planGithubIdentityRepair, applyGithubIdentityRepair } from "./identity.js";
+import { acceptGithubWebhook, reconcileGithubWebhooks, WebhookRefusal } from "./webhooks.js";
+export { acceptGithubWebhook, reconcileGithubWebhooks, WebhookRefusal } from "./webhooks.js";
 import http from "node:http";
 import https from "node:https";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { comments as pmCommentsFn, commitItemMutations as sdkCommitItemMutations, isExternalDependencyReference, listAllComplete, certifyCompleteListResult, listAllItemMetadata as sdkListAllItemMetadata, normalizeItemId as sdkNormalizeItemId, readSettings as sdkReadSettings, resolvePmRoot as sdkResolvePmRoot, getHistoryPath as sdkGetHistoryPath, readHistorySnapshot as sdkReadHistorySnapshot, } from "@unbrained/pm-cli/sdk";
+import { createPmCliExpectedError, comments as pmCommentsFn, commitItemMutations as sdkCommitItemMutations, isExternalDependencyReference, listAllComplete, certifyCompleteListResult, listAllItemMetadata as sdkListAllItemMetadata, normalizeItemId as sdkNormalizeItemId, readSettings as sdkReadSettings, resolvePmRoot as sdkResolvePmRoot, writeFileAtomic, getHistoryPath as sdkGetHistoryPath, readHistorySnapshot as sdkReadHistorySnapshot, } from "@unbrained/pm-cli/sdk";
 import { collectNewOrderingCycleWarnings as sdkCollectNewOrderingCycleWarnings } from "@unbrained/pm-cli/sdk/graph";
 import { GateInputError, formatGateReport, runTrackerGate, resolvePmDataDir, } from "./gate.js";
 export { resolvePmDataDir } from "./gate.js";
@@ -110,7 +115,10 @@ export function githubApiBase() {
             "Requests carry the GitHub token, so a plaintext non-loopback base would leak it.");
     }
     // Strip a trailing slash so `${base}/repos/...` cannot produce `//repos/...`.
-    return raw.replace(/\/+$/, "");
+    let end = raw.length;
+    while (raw[end - 1] === "/")
+        end--;
+    return raw.slice(0, end);
 }
 /**
  * One low-level HTTP request, with no retry or backoff.
@@ -968,9 +976,13 @@ export function deriveAtomicItemId(repo, issueNumber, idPrefix, normalizeItemId)
     return normalizeItemId(`github-${repoToken}-${issueNumber}`, idPrefix);
 }
 /** Map one rendered import entry to its reversible SDK mutation sequence. */
-export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemId) {
+export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemId, updateOnly = false) {
+    if (updateOnly && !entry.match?.id)
+        throw new CommandError("Refresh refuses an unlinked target; no item may be created.");
+    const changed = updateOnly ? new Set(refreshChanges(entry).map(change => change.field)) : undefined;
+    const audit = updateOnly ? { comment: [`Refreshed linked GitHub issue ${repo.toLowerCase()}#${entry.issueNumber}`] } : {};
     if (entry.linkOnly && entry.match?.id) {
-        return { itemId: entry.match.id, mutations: [{ op: "update", id: entry.match.id, options: { addTags: entry.tags } }] };
+        return { itemId: entry.match.id, mutations: [{ op: "update", id: entry.match.id, options: { ...(!changed || changed.has("tags") ? { addTags: entry.tags } : {}), ...audit } }] };
     }
     const sharedOptions = {
         title: entry.title,
@@ -995,7 +1007,7 @@ export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemI
     // item, but commitItemMutations must still receive the original plan. The
     // create step treats an existing stable id as already applied; update then
     // makes later content-bearing transactions refresh the item normally.
-    if (!entry.match?.id || entry.match.id === managedItemId) {
+    if (!updateOnly && (!entry.match?.id || entry.match.id === managedItemId)) {
         const createStatus = entry.status === "closed" ? "open" : entry.status;
         const mutations = [{
                 op: "create",
@@ -1024,7 +1036,13 @@ export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemI
         };
     }
     const itemId = entry.match.id;
-    const updateOptions = { ...sharedOptions, ...statusOptions };
+    const updateOptions = {
+        ...(updateOnly ? {
+            ...(changed.has("title") ? { title: entry.title } : {}),
+            ...(changed.has("tags") ? { tags: entry.tags.join(",") } : {}),
+            ...(changed.has("status") && sharedOptions.closeReason !== undefined ? { closeReason: sharedOptions.closeReason } : {}),
+        } : sharedOptions), ...(!changed || changed.has("status") ? statusOptions : {}), ...audit,
+    };
     const mutations = [{
             op: "update",
             id: itemId,
@@ -1058,36 +1076,82 @@ async function importContextVersions(pmRoot, entries) {
     }
     return versions;
 }
-/** Commit a complete issue-import batch under one crash-resumable transaction. */
-export async function importGithubAtomic(pmRoot, repo, entries, opts = {}) {
+/** Durable SDK journals live per tracker under `transactions/sdk`. */
+function sdkJournalDir(pmRoot) {
+    return path.join(pmRoot, "transactions", "sdk");
+}
+/** Persisted import plans live beside the SDK journals, under `transactions/pm-github`. */
+function importPlanDir(pmRoot) {
+    return path.join(pmRoot, "transactions", "pm-github");
+}
+/** Extract the mutation target ids from journal step ids like `1-update-<item>-<hash>`. @internal */
+export function journalStepItemIds(stepIds) {
+    const ids = new Set();
+    for (const step of stepIds) {
+        const id = typeof step === "string" ? /^\d+-(?:create|update|close|release)-(.+)-[0-9a-f]{12}$/.exec(step)?.[1] : undefined;
+        if (id !== undefined)
+            ids.add(id);
+    }
+    return [...ids];
+}
+/** List pending github-import journals without changing plans or tracker bytes. */
+export async function listUnfinishedGithubImports(pmRoot) {
     pmRoot = sdkResolvePmRoot(process.cwd(), pmRoot);
-    const { commitItemMutations: commit, normalizeItemId, readSettings, } = await resolveAtomicSdkFunctions(opts);
-    let idPrefix = "pm-";
+    const unfinished = [];
+    const journalNames = await fs.promises.readdir(sdkJournalDir(pmRoot)).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw new CommandError("Refresh cannot inspect GitHub transaction journals.");
+    });
+    for (const name of journalNames) {
+        if (!name.startsWith(ATOMIC_IMPORT_PREFIX) || !name.endsWith(".json"))
+            continue;
+        const transactionId = name.slice(0, -".json".length);
+        let journal;
+        try {
+            journal = JSON.parse(await fs.promises.readFile(path.join(sdkJournalDir(pmRoot), name), "utf8"));
+            if (!journal || typeof journal !== "object")
+                throw new Error("Invalid journal");
+        }
+        catch {
+            throw new CommandError(`Refresh cannot inspect GitHub transaction ${transactionId}: its durable journal is unreadable.`);
+        }
+        if (journal.status === "applying" || journal.status === "compensating") {
+            unfinished.push({ transactionId, status: journal.status,
+                itemIds: journalStepItemIds(Array.isArray(journal.stepIds) ? journal.stepIds : []) });
+        }
+    }
+    return unfinished.sort((left, right) => left.transactionId.localeCompare(right.transactionId));
+}
+/** Persist the exact pre-commit plan so an interrupted journal can be replayed verbatim. */
+async function persistGithubImportPlan(pmRoot, record) {
+    await fs.promises.mkdir(importPlanDir(pmRoot), { recursive: true });
+    await writeFileAtomic(path.join(importPlanDir(pmRoot), `${record.transactionId}.json`), `${JSON.stringify(record, null, 2)}\n`);
+}
+/** Read one persisted plan; null when the tracker holds no plan for that transaction. */
+export async function readGithubImportPlan(pmRoot, transactionId) {
+    if (!/^[a-zA-Z0-9._-]+$/.test(transactionId))
+        return null;
+    const file = path.join(importPlanDir(sdkResolvePmRoot(process.cwd(), pmRoot)), `${transactionId}.json`);
     try {
-        const settings = await readSettings(pmRoot);
-        if (settings?.id_prefix)
-            idPrefix = String(settings.id_prefix);
+        return JSON.parse(await fs.promises.readFile(file, "utf8"));
     }
     catch {
-        // Match normal import resilience: an unreadable optional setting falls
-        // back to the canonical prefix; the mutation still validates the tracker.
-    }
-    const mutations = [];
-    const itemIds = new Map();
-    // The transaction journal fingerprints the ordered step plan. Canonicalize
-    // by the stable GitHub issue number so a retry whose API page/order changed
-    // supplies the exact same plan as well as the same transaction id.
-    for (const entry of [...entries].sort((a, b) => a.issueNumber - b.issueNumber)) {
-        const planned = buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemId);
-        itemIds.set(entry.issueNumber, planned.itemId);
-        mutations.push(...planned.mutations);
+        return null;
     }
-    const transactionId = deriveAtomicTransactionId(repo, entries, mutations, await importContextVersions(pmRoot, entries));
+}
+/** Remove a persisted plan once its journal reached a durable terminal state. */
+async function removeGithubImportPlan(pmRoot, transactionId) {
+    await fs.promises.rm(path.join(importPlanDir(pmRoot), `${transactionId}.json`), { force: true });
+}
+/** Finalize source metadata and commit one github-import transaction through the SDK. */
+async function commitGithubImportTransaction(config) {
+    const { pmRoot, entries, mutations, transactionId, itemIds, opts, commit } = config;
     /** Finalize before the SDK commits, and repair source metadata on recovered journals. */
     const finalize = async () => {
         for (const entry of entries) {
             if (entry.fidelity)
-                await persistImportFidelity(pmRoot, itemIds.get(entry.issueNumber), entry.fidelity, Boolean(entry.linkOnly));
+                await persistImportFidelity(pmRoot, itemIds.get(entry.issueNumber), entry.fidelity, Boolean(entry.linkOnly), opts.updateOnly);
         }
     };
     let committed = false;
@@ -1125,18 +1189,145 @@ export async function importGithubAtomic(pmRoot, repo, entries, opts = {}) {
         };
     }
     catch (err) {
+        // Retain sensitive replay data only while the durable journal is resumable.
+        // Apply this to fresh commits and recovery attempts, preserving the original
+        // failure when journal inspection or cleanup itself is unavailable.
+        if (opts.updateOnly) {
+            const pending = await listUnfinishedGithubImports(pmRoot).catch(() => null);
+            if (pending && !pending.some(journal => journal.transactionId === transactionId)) {
+                await removeGithubImportPlan(pmRoot, transactionId).catch(() => { });
+            }
+        }
         const msg = errorMessage(err);
+        const label = `${opts.updateOnly ? "Refresh" : "Atomic GitHub import"} transaction ${transactionId}`;
         if (committed)
-            throw new CommandError(`Atomic GitHub import has a committed journal but source metadata could not be finalized. Retry transaction ${transactionId}; nothing may be pushed. Underlying error: ${msg}`);
+            throw new CommandError(`${label} has a committed journal but source metadata could not be finalized. Retry transaction ${transactionId}; nothing may be pushed. Underlying error: ${msg}`);
         if (err instanceof AggregateError || /compensation failed/i.test(msg)) {
-            throw new CommandError(`Atomic GitHub import failed and compensation was incomplete. The tracker may contain partially applied state; retry the same import to resume transaction ${transactionId}, then inspect its durable journal if recovery still fails. Underlying error: ${msg}`, EXIT_CODE.GENERIC_FAILURE);
+            throw new CommandError(`${label} failed and compensation was incomplete. The tracker may contain partially applied state; retry to resume transaction ${transactionId}, then inspect its durable journal if recovery still fails. Underlying error: ${msg}`, EXIT_CODE.GENERIC_FAILURE);
         }
         if (err instanceof Error && err.name === "WorkspaceTransactionInterruptedError") {
-            throw new CommandError(`Atomic GitHub import was interrupted. Its durable journal is resumable; retry the same import to continue transaction ${transactionId}. Underlying error: ${msg}`, EXIT_CODE.GENERIC_FAILURE);
+            throw new CommandError(`${label} was interrupted. Its durable journal is resumable; retry to continue transaction ${transactionId}. Underlying error: ${msg}`, EXIT_CODE.GENERIC_FAILURE);
         }
-        throw new CommandError(`Atomic GitHub import failed after the SDK completed its normal compensation path; no new partial committed state is expected. Transaction id: ${transactionId}. Underlying error: ${msg}`, EXIT_CODE.GENERIC_FAILURE);
+        throw new CommandError(`${label} failed after the SDK completed its normal compensation path; no new partial committed state is expected. Underlying error: ${msg}`, EXIT_CODE.GENERIC_FAILURE);
     }
 }
+/** Commit a complete issue-import batch under one crash-resumable transaction. */
+export async function importGithubAtomic(pmRoot, repo, entries, opts = {}) {
+    pmRoot = sdkResolvePmRoot(process.cwd(), pmRoot);
+    const { commitItemMutations: commit, normalizeItemId, readSettings, } = await resolveAtomicSdkFunctions(opts);
+    let idPrefix = "pm-";
+    try {
+        const settings = await readSettings(pmRoot);
+        if (settings?.id_prefix)
+            idPrefix = String(settings.id_prefix);
+    }
+    catch {
+        // Match normal import resilience: an unreadable optional setting falls
+        // back to the canonical prefix; the mutation still validates the tracker.
+    }
+    const mutations = [];
+    const itemIds = new Map();
+    // The transaction journal fingerprints the ordered step plan. Canonicalize
+    // by the stable GitHub issue number so a retry whose API page/order changed
+    // supplies the exact same plan as well as the same transaction id.
+    for (const entry of [...entries].sort((a, b) => a.issueNumber - b.issueNumber)) {
+        const planned = buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemId, opts.updateOnly);
+        itemIds.set(entry.issueNumber, planned.itemId);
+        mutations.push(...planned.mutations);
+    }
+    const transactionId = deriveAtomicTransactionId(repo, entries, mutations, await importContextVersions(pmRoot, entries));
+    // Update-only transactions derive their steps from the CURRENT item state,
+    // so a retry after a partial apply would fingerprint a different plan and
+    // orphan the journal behind a fresh transaction id. Persist the exact plan
+    // before the SDK touches the tracker so an interrupted refresh can replay it.
+    if (opts.updateOnly)
+        for (const entry of entries)
+            validateGithubImportFidelity(entry, repo, `GitHub transaction ${transactionId}`);
+    const plan = opts.updateOnly ? { transactionId, repo: repo.toLowerCase(), entries, mutations } : undefined;
+    if (plan)
+        await persistGithubImportPlan(pmRoot, plan);
+    const result = await commitGithubImportTransaction({ pmRoot, repo, entries, mutations, transactionId, itemIds, opts, commit });
+    if (plan)
+        await removeGithubImportPlan(pmRoot, transactionId);
+    return result;
+}
+/** Validate every source-finalization input against its effective native lifecycle before writes. */
+export function validateGithubImportFidelity(entry, repo, context, items) {
+    // Finalization reads source metadata outside the SDK mutation preview.
+    // Validate its entire projection before ANY selected journal can commit.
+    const fidelity = entry.fidelity;
+    if (fidelity !== undefined) {
+        const fields = ["github_url", "github_number", "github_state", "github_state_reason", "github_created_at",
+            "github_updated_at", "github_closed_at", "github_close_reason", "github_release"];
+        if (!fidelity || typeof fidelity !== "object" || Array.isArray(fidelity) ||
+            Object.keys(fidelity).some(field => !fields.includes(field)) ||
+            typeof fidelity.github_url !== "string" ||
+            fidelity.github_url.toLowerCase() !== `https://github.com/${repo.toLowerCase()}/issues/${entry.issueNumber}` ||
+            fidelity.github_number !== entry.issueNumber ||
+            !["open", "closed"].includes(fidelity.github_state) ||
+            typeof fidelity.github_created_at !== "string" || typeof fidelity.github_updated_at !== "string" ||
+            [fidelity.github_closed_at, fidelity.github_close_reason, fidelity.github_release, fidelity.github_state_reason]
+                .some(value => value !== null && typeof value !== "string")) {
+            throw new CommandError(`${context}: its persisted fidelity is invalid.`);
+        }
+        try {
+            validateImportLifetime({ number: entry.issueNumber, created_at: fidelity.github_created_at,
+                updated_at: fidelity.github_updated_at, closed_at: fidelity.github_closed_at });
+        }
+        catch {
+            throw new CommandError(`${context}: its persisted fidelity has an invalid source lifetime.`);
+        }
+        // Missing source closure dates preserve native completion metadata.
+        // Check the effective lifecycle from the current read-only snapshot too.
+        const current = items?.find(item => item.id === entry.match.id) ?? entry.match;
+        const projected = { ...current, ...importFidelityFields(fidelity, Boolean(entry.linkOnly)) };
+        if (projected.closed_at && Date.parse(String(projected.closed_at)) < Date.parse(String(projected.created_at))) {
+            throw new CommandError(`${context}: its persisted fidelity conflicts with the native closure date.`);
+        }
+    }
+    if (entry.linkOnly !== undefined && typeof entry.linkOnly !== "boolean") {
+        throw new CommandError(`${context}: its persisted ownership is invalid.`);
+    }
+}
+/** Validate a persisted refresh plan without writing or opening an SDK transaction. */
+export function validateGithubImportPlan(record, items) {
+    if (typeof record?.transactionId !== "string" || !/^[a-zA-Z0-9._-]+$/.test(record.transactionId) ||
+        typeof record.repo !== "string" || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(record.repo) ||
+        !Array.isArray(record.entries) || !record.entries.length || !Array.isArray(record.mutations) || !record.mutations.length) {
+        throw new CommandError(`Refresh cannot replay unfinished GitHub transaction ${typeof record?.transactionId === "string" ? record.transactionId : "<unknown>"}: its persisted plan is invalid.`, EXIT_CODE.GENERIC_FAILURE);
+    }
+    const itemIds = new Map();
+    for (const entry of record.entries) {
+        if (typeof entry?.issueNumber !== "number" || typeof entry?.match?.id !== "string") {
+            throw new CommandError(`Refresh cannot replay unfinished GitHub transaction ${record.transactionId}: its persisted plan has an unlinked target.`, EXIT_CODE.GENERIC_FAILURE);
+        }
+        validateGithubImportFidelity(entry, record.repo, `Refresh cannot replay unfinished GitHub transaction ${record.transactionId}`, items);
+        itemIds.set(entry.issueNumber, entry.match.id);
+    }
+    if (record.mutations.some(mutation => mutation?.op !== "update" || ![...itemIds.values()].includes(mutation.id))) {
+        throw new CommandError(`Refresh cannot replay unfinished GitHub transaction ${record.transactionId}: its persisted mutation targets are invalid.`);
+    }
+    return itemIds;
+}
+/**
+ * Resume one interrupted github-import journal by replaying its persisted
+ * original plan. The plan — never a re-derivation from current item state —
+ * supplies the exact ordered mutations and the transaction id, because a
+ * partial apply changes both the derived step set and the history context the
+ * id is fingerprinted from. When the recorded plan cannot be trusted, the
+ * caller fails closed instead of leaving the journal silently unfinished.
+ */
+export async function resumeGithubImport(pmRoot, record, opts = {}) {
+    pmRoot = sdkResolvePmRoot(process.cwd(), pmRoot);
+    const itemIds = validateGithubImportPlan(record);
+    const { commitItemMutations: commit } = await resolveAtomicSdkFunctions(opts);
+    const result = await commitGithubImportTransaction({
+        pmRoot, repo: record.repo, entries: record.entries, mutations: record.mutations,
+        transactionId: record.transactionId, itemIds, opts: { ...opts, updateOnly: true }, commit,
+    });
+    await removeGithubImportPlan(pmRoot, record.transactionId);
+    return result;
+}
 // ---------------------------------------------------------------------------
 // Shared import core (used by both the legacy command and the importer)
 // ---------------------------------------------------------------------------
@@ -1940,6 +2131,7 @@ export function parseImportOptions(options) {
         atomic: optionEnabled(options, "atomic"),
         linkDeps: optionEnabled(options, "link-deps", "linkDeps"),
         gate: optionEnabled(options, "gate"),
+        adoptCited: optionEnabled(options, "adopt-cited", "adoptCited"),
     };
 }
 // Spawn the `pm` CLI with the given argv and return a normalized ok/stdout/stderr
@@ -2222,11 +2414,11 @@ export async function linkImportedDependencies(repo, issues, pmRoot, deps = {})
  * @param fetchIssueComments - Injectable comment fetcher (defaults to {@link fetchComments}).
  * @returns The prepared import entry, or `undefined` when the issue has no title.
  */
-async function prepareGithubImport(issue, repo, opts, token, match, fetchIssueComments = fetchComments, fidelityContext) {
+export async function prepareGithubImport(issue, repo, opts, token, match, fetchIssueComments = fetchComments, fidelityContext) {
     const title = issue.title.trim();
     if (!title)
         return undefined;
-    const identity = matchImportedIssue(fidelityContext.items, issue, match);
+    const identity = matchImportedIssue(fidelityContext.items, issue, match, opts.adoptCited === true);
     match = identity.item;
     const timeline = await fidelityContext.timeline(issue, repo, token);
     const fidelity = buildImportFidelity(issue, fidelityContext.releases, timeline);
@@ -2264,7 +2456,7 @@ async function prepareGithubImport(issue, repo, opts, token, match, fetchIssueCo
             (issue.state_reason ? ` · state reason ${issue.state_reason}` : "") +
             ` · created ${issue.created_at} · updated ${issue.updated_at}`,
         body: writeCommentsToBody ? composeBody(issue, comments) : (issue.body || ""),
-        tags: [...new Set([...(identity.linkOnly ? match.tags : []), ...labels, tag, ...(ghAuthorTag ? [ghAuthorTag] : [])])],
+        tags: [...new Set([...(identity.linkOnly || identity.via === "citation" ? match.tags ?? [] : []), ...labels, tag, ...(ghAuthorTag ? [ghAuthorTag] : [])])],
         assignee: issue.assignee?.login,
         milestone: issue.milestone?.title,
         comments,
@@ -2273,6 +2465,7 @@ async function prepareGithubImport(issue, repo, opts, token, match, fetchIssueCo
         fidelity,
         linkOnly: identity.linkOnly,
         identity: { via: identity.via, ...(conflict ? { conflict } : {}) },
+        ...(identity.citation_candidates ? { citation_candidates: identity.citation_candidates } : {}),
         match,
     };
 }
@@ -2353,6 +2546,8 @@ export function verifyImportIdempotency(existing, prepared, repo) {
     for (const entry of prepared) {
         if (entry.match?.id) {
             matchedIds.push(entry.match.id);
+            if (entry.identity?.via === "citation" && !entry.tags.includes(provenanceTag(repo, entry.issueNumber)))
+                untaggedNewEntries++;
             continue;
         }
         if (!entry.tags.includes(provenanceTag(repo, entry.issueNumber)))
@@ -2365,8 +2560,9 @@ export function verifyImportIdempotency(existing, prepared, repo) {
             `${conflictingTargets} conflicting target(s). No item was written.`, EXIT_CODE.GENERIC_FAILURE);
     }
     return {
+        adopted: prepared.filter(entry => entry.identity?.via === "citation").length,
         provenance_indexed: tagOwners.size,
-        matched_by_provenance: matchedIds.length,
+        matched_by_provenance: prepared.filter(entry => entry.match?.id && entry.identity?.via !== "citation").length,
         new_entries: prepared.length - matchedIds.length,
     };
 }
@@ -2496,12 +2692,13 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                 dryRun: true,
                 wouldImport: 0,
                 wouldUpdate: 0,
+                wouldAdopt: 0,
                 wouldSkip: 0,
                 ...(opts.atomic ? { atomic: true } : {}),
                 ...fetchFields,
             };
         }
-        return { imported: 0, updated: 0, skipped: 0, ...fetchFields, ...(emptyGateReceipt ? { gate: emptyGateReceipt } : {}) };
+        return { imported: 0, updated: 0, adopted: 0, skipped: 0, ...fetchFields, ...(emptyGateReceipt ? { gate: emptyGateReceipt } : {}) };
     }
     console.error(`Found ${filtered.length} issue(s).`);
     // Build the idempotency index once up-front — including for a dry run. Skipping
@@ -2522,13 +2719,14 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         timeline: dependencies.fetchIssueTimeline ?? (dependencies.fetchIssues ? async () => [] : fetchImportTimeline) };
     let imported = 0;
     let updated = 0;
+    let adopted = 0;
     let skipped = 0;
     // Planned native comments the write phase could not land (contended lock,
     // refused add, unparsable created id). Ungated runs warn and continue; gated
     // runs add this to the plan-divergence refusal at the end.
     let commentWriteFailures = 0;
-    // Gated pipeline, phase 1 — plan BEFORE any mutation. The same prepare step
-    // the write paths use builds every plan entry up front, so completeness
+    // Plan every import BEFORE any mutation, including ungated citation refusals.
+    // The same prepare step builds every entry up front, so gated completeness
     // (every fetched issue accounted for exactly once) and idempotency (every
     // re-import lands on exactly one provenance-tagged item) are proven while
     // the tracker is still untouched. Both checks throw before any write.
@@ -2536,19 +2734,48 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
     let gateCompleteness;
     let gateIdempotency;
     let gatePlanByNumber;
-    if (opts.gate || opts.atomic) {
+    const citationCandidates = [];
+    let citationReceipt = {};
+    {
         const planned = [];
         const skippedNumbers = [];
+        const ambiguous = [];
         for (const issue of filtered) {
-            const entry = await prepareGithubImport(issue, repo, opts, token, existing.get(`${repo.toLowerCase()}#${issue.number}`), dependencies.fetchIssueComments, fidelityContext);
+            let entry;
+            try {
+                entry = await prepareGithubImport(issue, repo, opts, token, existing.get(`${repo.toLowerCase()}#${issue.number}`), dependencies.fetchIssueComments, fidelityContext);
+            }
+            catch (error) {
+                if (!(error instanceof AmbiguousCitationError))
+                    throw error;
+                ambiguous.push(error.entry);
+                for (const candidate of error.entry.citation_candidates ?? [])
+                    citationCandidates.push({ issue: issue.number, ...candidate });
+                continue;
+            }
             if (!entry) {
                 skippedNumbers.push(issue.number);
                 continue;
             }
             planned.push(entry);
+            for (const candidate of entry.citation_candidates ?? [])
+                citationCandidates.push({ issue: issue.number, ...candidate });
+        }
+        if (citationCandidates.length > 0)
+            citationReceipt = { citation_candidates: citationCandidates };
+        if (ambiguous.length > 0) {
+            const refusal = { code: "ambiguous_citation", blocked: true, plan: ambiguous, ...citationReceipt };
+            if (!opts.dryRun)
+                throw new CommandError(JSON.stringify(refusal));
+            for (const entry of ambiguous)
+                console.error(`[dry-run] #${entry.issue} ambiguous_citation: ${entry.candidates.join(", ")}. ${entry.remedy}`);
+            return { dryRun: true, wouldImport: 0, wouldUpdate: 0, wouldAdopt: 0, wouldSkip: skippedNumbers.length,
+                ...(opts.atomic ? { atomic: true } : {}), ...refusal, ...fetchFields };
         }
         if (opts.gate) {
             gateCompleteness = verifyImportPlanCompleteness(filtered, planned, skippedNumbers);
+        }
+        if (opts.gate || planned.some(entry => entry.identity?.via === "citation")) {
             gateIdempotency = verifyImportIdempotency(existingItems, planned, repo);
         }
         gatePlan = planned;
@@ -2568,23 +2795,26 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         }
         if (opts.gate)
             console.error(`pm github gate: plan verified — ${gateCompleteness.planned} planned, ${gateCompleteness.skipped} skipped, ` +
-                `${gateIdempotency.matched_by_provenance} matched by provenance, ${gateIdempotency.new_entries} new.`);
+                `${gateIdempotency.matched_by_provenance} matched by provenance, ${gateIdempotency.adopted} adopted, ${gateIdempotency.new_entries} new.`);
     }
     // Preview output omits unscanned PR-title quotes and private provider close text.
     const fidelityPlan = () => gatePlan.map(entry => {
         const source = entry.fidelity;
         const reason = source.github_close_reason.split(" (", 1)[0];
         return { issue: entry.issueNumber, item: entry.match?.id,
-            action: entry.linkOnly ? "link" : entry.match?.id ? "update" : "create", status: entry.status,
+            action: entry.identity?.via === "citation" ? "adopt" : entry.linkOnly ? "link" : entry.match?.id ? "update" : "create", status: entry.status,
             ...source, github_close_reason: reason,
             created_at: entry.linkOnly ? entry.match.created_at : source.github_created_at,
             updated_at_policy: "sdk-mutation-clock; source in github_updated_at",
             closed_at: entry.linkOnly ? entry.match.closed_at : source.github_closed_at,
             close_reason: entry.linkOnly ? "preserved-provider-owner" : reason,
             release: entry.linkOnly ? "preserved-provider-owner" : source.github_release,
-            identity: entry.identity };
+            identity: entry.identity,
+            ...(entry.citation_candidates ? { citation_candidates: entry.citation_candidates } : {}) };
     });
-    const gatePlanFields = opts.gate ? { plan: fidelityPlan(), gate: { completeness: gateCompleteness, idempotency: gateIdempotency, scan: "post-write" } } : {};
+    const adoptionCount = gatePlan.filter(entry => entry.identity?.via === "citation").length;
+    const planFields = { ...(opts.gate || adoptionCount > 0 || citationCandidates.length > 0 ? { plan: fidelityPlan() } : {}), ...citationReceipt };
+    const gatePlanFields = { ...planFields, ...(opts.gate ? { gate: { completeness: gateCompleteness, idempotency: gateIdempotency, scan: "post-write" } } : {}) };
     if (opts.atomic) {
         // The gated pipeline already prepared every entry (and counted its skips)
         // during the pre-mutation plan phase; reuse that plan verbatim so the write
@@ -2597,6 +2827,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                     dryRun: true,
                     wouldImport: 0,
                     wouldUpdate: 0,
+                    wouldAdopt: 0,
                     wouldSkip: skipped,
                     atomic: true,
                     ...fetchFields,
@@ -2606,12 +2837,12 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         }
         if (opts.dryRun) {
             imported = prepared.filter((entry) => !entry.match?.id).length;
-            updated = prepared.length - imported;
+            updated = prepared.length - imported - adoptionCount;
             for (const entry of prepared) {
-                const action = entry.match?.id ? "update" : "import";
+                const action = entry.identity?.via === "citation" ? "adopt" : entry.match?.id ? "update" : "import";
                 console.error(`  [dry-run][atomic] #${entry.issueNumber} ${action}: ${opts.gate ? "(gated title)" : entry.title} (${entry.status})`);
             }
-            console.error(`[dry-run] Atomic plan would import ${imported}, update ${updated}, skip ${skipped}.`);
+            console.error(`[dry-run] Atomic plan would import ${imported}, update ${updated}, skip ${skipped}. Adopt ${adoptionCount}.`);
             if (opts.linkDeps) {
                 console.error(`[dry-run] --link-deps: ${countDependencyRefCandidates(repo, filtered)} candidate reference(s) parsed; ` +
                     `resolution + edge writes run only on a real import.`);
@@ -2620,6 +2851,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                 dryRun: true,
                 wouldImport: imported,
                 wouldUpdate: updated,
+                wouldAdopt: adoptionCount,
                 wouldSkip: skipped,
                 atomic: true,
                 ...(opts.linkDeps ? { wouldLinkDependencyCandidates: countDependencyRefCandidates(repo, filtered) } : {}),
@@ -2666,28 +2898,21 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             transactionId: result.transactionId,
             recovered: result.recovered,
             imported: result.imported,
-            updated: result.updated,
+            updated: result.updated - (result.recovered ? 0 : adoptionCount),
+            adopted: result.recovered ? 0 : adoptionCount,
             ...(result.recoveredItems !== undefined ? { recoveredItems: result.recoveredItems } : {}),
             skipped,
             atomic: true,
             ...depLinkResultFields(atomicDepLink),
             ...fetchFields,
-            ...(opts.gate ? { plan: fidelityPlan() } : {}),
+            ...planFields,
             ...(gateReceipt ? { gate: gateReceipt } : {}),
         };
     }
     for (const issue of filtered) {
-        // With --gate, the pre-mutation plan phase already prepared (or explicitly
-        // skipped) every issue; reuse the verified plan instead of re-preparing so
-        // the write phase cannot diverge from it.
-        const prepared = gatePlanByNumber
-            ? gatePlanByNumber.get(issue.number)
-            : await prepareGithubImport(issue, repo, opts, token, existing.get(`${repo.toLowerCase()}#${issue.number}`), dependencies.fetchIssueComments, fidelityContext);
+        // Every import reuses the pre-mutation identity plan, including ungated runs.
+        const prepared = gatePlanByNumber.get(issue.number);
         if (!prepared) {
-            // A gated run counted its skips during the verified plan phase; only the
-            // ungated path counts them here.
-            if (!gatePlanByNumber)
-                skipped++;
             continue;
         }
         const labels = issue.labels.map((l) => l.name).filter(Boolean);
@@ -2707,10 +2932,12 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             return args;
         };
         if (opts.dryRun) {
-            const action = match?.id ? "update" : "import";
+            const action = prepared.identity?.via === "citation" ? "adopt" : match?.id ? "update" : "import";
             const metadata = !opts.gate && labels.length > 0 ? `${status}, ${labels.join(",")}` : status;
             console.error(`  [dry-run] #${issue.number} ${action}: ${opts.gate ? "(gated title)" : title} (${metadata})`);
-            if (match?.id)
+            if (prepared.identity?.via === "citation")
+                adopted++;
+            else if (match?.id)
                 updated++;
             else
                 imported++;
@@ -2722,7 +2949,10 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             if (!linked.ok)
                 throw new CommandError(`Could not link GitHub issue #${issue.number} to its existing owner.`);
             await persistImportFidelity(pmRoot, ownerId, prepared.fidelity, true);
-            updated++;
+            if (prepared.identity?.via === "citation")
+                adopted++;
+            else
+                updated++;
             continue;
         }
         if (match?.id) {
@@ -2774,7 +3004,10 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                 commentWriteFailures += (await syncGithubCommentsToAnnotations(match.id, comments, pmRoot, issue.number)).failed;
             }
             await persistImportFidelity(pmRoot, match.id, prepared.fidelity, false);
-            updated++;
+            if (prepared.identity?.via === "citation")
+                adopted++;
+            else
+                updated++;
             continue;
         }
         // A closed upstream issue cannot be born closed: governance
@@ -2846,7 +3079,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         imported++;
     }
     if (opts.dryRun) {
-        console.error(`[dry-run] Would import ${imported}, update ${updated}, skip ${skipped}.`);
+        console.error(`[dry-run] Would import ${imported}, update ${updated}, skip ${skipped}. Adopt ${adopted}.`);
         if (opts.linkDeps) {
             console.error(`[dry-run] --link-deps: ${countDependencyRefCandidates(repo, filtered)} candidate reference(s) parsed; ` +
                 `resolution + edge writes run only on a real import.`);
@@ -2855,14 +3088,15 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             dryRun: true,
             wouldImport: imported,
             wouldUpdate: updated,
+            wouldAdopt: adopted,
             wouldSkip: skipped,
             ...(opts.linkDeps ? { wouldLinkDependencyCandidates: countDependencyRefCandidates(repo, filtered) } : {}),
             ...gatePlanFields,
             ...fetchFields,
         };
     }
-    console.error(`Imported ${imported} new, updated ${updated} existing, skipped ${skipped}.`);
-    if (imported === 0 && updated === 0 && skipped > 0) {
+    console.error(`Imported ${imported} new, updated ${updated} existing, adopted ${adopted}, skipped ${skipped}.`);
+    if (imported === 0 && updated === 0 && adopted === 0 && skipped > 0) {
         throw new CommandError(`Imported 0 issue(s); ${skipped} failed.`);
     }
     // A gated import is all-or-nothing in effect: a planned write that failed
@@ -2880,7 +3114,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
     if (opts.gate)
         verifyImportedProvenance(await readImportItems(), gatePlan, repo);
     const gateReceipt = opts.gate ? gateImportWrites(pmRoot) : undefined;
-    return { imported, updated, skipped, ...fetchFields, ...depLinkResultFields(depLink), ...(opts.gate ? { plan: fidelityPlan() } : {}), ...(gateReceipt ? { gate: gateReceipt } : {}) };
+    return { imported, updated, adopted, skipped, ...fetchFields, ...depLinkResultFields(depLink), ...planFields, ...(gateReceipt ? { gate: gateReceipt } : {}) };
 }
 /**
  * Emit the human-readable `--link-deps` summary to stderr.
@@ -4201,7 +4435,7 @@ export async function githubGraphQL(token, query, variables) {
     return (await githubGraphQLResponse(token, query, variables)).data;
 }
 /** Shared GraphQL client retaining partial errors for reference-level classification. */
-async function githubGraphQLResponse(token, query, variables) {
+export async function githubGraphQLResponse(token, query, variables) {
     if (!token) {
         throw new CommandError("GitHub GraphQL requires a token (set GITHUB_TOKEN/GH_TOKEN or run `gh auth login`).", EXIT_CODE.USAGE);
     }
@@ -4971,7 +5205,7 @@ async function runProjectSync(ctx) {
 export function isMutatingGithubCommand(command, options) {
     const cmd = (command || "").toLowerCase();
     const dryRun = optionEnabled(options, "dry-run", "dryRun");
-    if (cmd === "github sync")
+    if (cmd === "github sync" || cmd === "github refresh")
         return !dryRun;
     // Export is dry-run by default; it only mutates with an explicit apply
     // (--apply / --no-dry-run / legacy --push) AND no --dry-run override.
@@ -4991,6 +5225,7 @@ export function isMutatingGithubCommand(command, options) {
 // Extension
 // ---------------------------------------------------------------------------
 const IMPORT_FLAGS = [
+    { long: "--adopt-cited", description: "Opt in to normalized, anchored citation adoption (default: off). Tag items gh:owner/repo#N when creating them; default imports only report citation candidates" },
     { long: "--issue", value_name: "N[,N...]", description: "Fetch exactly these issue numbers, #N, or same-repo owner/repo#N references; conflicts with --state/--all/--labels/--since/--assignee/--milestone/--limit. Missing numbers fail before writes (reported by --dry-run); PRs require --include-prs" },
     { long: "--limit", value_name: "n", description: "Positive list-mode issue cap, newest-updated first; reports limit and truncated when more exist (one extra matching issue is fetched to check). Invalid with --issue" },
     { long: "--all", description: "Include closed issues (shorthand for --state all)" },
@@ -5072,7 +5307,7 @@ const PROJECT_SYNC_FLAGS = [
 const defineExtension = (module) => module;
 export default defineExtension({
     name: "pm-github",
-    version: "2026.10.19",
+    version: "2026.10.23",
     activate(api) {
         // -----------------------------------------------------------------------
         // schema — declare the GitHub provenance fields so the workspace knows them
@@ -5103,6 +5338,7 @@ export default defineExtension({
         api.registerPreflight({
             commands: [
                 "github sync",
+                "github refresh",
                 "github export",
                 "github import",
                 "gh-issues import",
@@ -5284,6 +5520,88 @@ export default defineExtension({
             },
         });
         // -----------------------------------------------------------------------
+        // Refresh uses the import planner and its guarded update-only transaction path.
+        api.registerCommand({
+            name: "github identity",
+            description: "Explore exact identity collisions and copied mentions offline. Defaults to a bounded read-only graph; --owner and --detach preview one repair, --approve applies its exact digest.",
+            flags: [
+                { long: "--identity", value_name: "ref", description: "Exact gh:owner/repo#N or external_ref to inspect" },
+                { long: "--limit", value_name: "N", description: "Identity groups per page, 1..100 (default 20)" },
+                { long: "--offset", value_name: "N", description: "Zero-based identity page offset" },
+                { long: "--owner", value_name: "id", description: "Independently declared rightful owner" },
+                { long: "--detach", value_name: "id", description: "One duplicate whose GitHub tag may be removed" },
+                { long: "--approve", value_name: "digest", description: "Apply the exact reviewed preview digest" },
+            ],
+            async run(ctx) {
+                const options = ctx.options;
+                if (options.owner !== undefined || options.detach !== undefined || options.approve !== undefined) {
+                    if (typeof options.identity !== "string" || typeof options.owner !== "string" || typeof options.detach !== "string" ||
+                        (options.approve !== undefined && typeof options.approve !== "string")) {
+                        throw createPmCliExpectedError("Supply --identity, --owner and --detach together; --approve requires the preview digest.", { context: { code: "invalid_options" } });
+                    }
+                    return options.approve === undefined
+                        ? planGithubIdentityRepair(ctx.pm_root, options.identity, options.owner, options.detach)
+                        : applyGithubIdentityRepair(ctx.pm_root, { identity: options.identity, owner: options.owner, detach: options.detach, approval: options.approve, author: process.env.PM_AUTHOR ?? "pm-github" });
+                }
+                return exploreGithubIdentities(ctx.pm_root, {
+                    limit: options.limit === undefined ? undefined : Number(options.limit),
+                    offset: options.offset === undefined ? undefined : Number(options.offset),
+                    identity: typeof options.identity === "string" ? options.identity : undefined,
+                });
+            },
+        });
+        api.registerCommand({
+            name: "github refresh",
+            description: "Refresh existing linked items from GitHub without importing new issues.",
+            intent: "keep a selected GitHub mirror current",
+            arguments: [{ name: "owner/repo", required: true, description: "Linked GitHub repository" }],
+            flags: [
+                { long: "--dry-run", description: "Preview linked-item field changes without writing the tracker" },
+                { long: "--since", value_name: "date|relative", description: "Only apply issues updated since this date or relative duration" },
+                { long: "--limit", value_name: "N", description: "Select at most N linked issue numbers, in ascending order, before fetching" },
+                { long: "--atomic", description: "Commit all changed linked items in one workspace writer transaction; an interrupted transaction is replayed from its persisted plan on the next refresh before unchanged items are skipped" },
+            ],
+            async run(ctx) {
+                return runRefresh(ctx.args[0], ctx.pm_root, ctx.options);
+            },
+        });
+        api.registerCommand({
+            name: "github webhook receive",
+            description: "Verify and durably deduplicate an explicitly supplied issues webhook. Reads PM_GITHUB_WEBHOOK_SECRET; never stores payloads or changes items.",
+            arguments: [{ name: "owner/repo", required: true, description: "Expected repository boundary" }],
+            flags: [
+                { long: "--payload", value_name: "file", description: "File containing the exact original request body bytes" },
+                { long: "--delivery", value_name: "id", description: "Original X-GitHub-Delivery header" },
+                { long: "--event", value_name: "type", description: "Original X-GitHub-Event header (issues)" },
+                { long: "--signature", value_name: "sha256=...", description: "Original X-Hub-Signature-256 header" },
+            ],
+            async run(ctx) {
+                const { payload, delivery, event, signature } = ctx.options;
+                if (!ctx.args[0] || typeof payload !== "string" || typeof delivery !== "string" || typeof event !== "string" || typeof signature !== "string") {
+                    throw new WebhookRefusal("invalid_options", "Supply owner/repo and --payload, --delivery, --event, --signature; set PM_GITHUB_WEBHOOK_SECRET securely.");
+                }
+                let bytes;
+                try {
+                    if (fs.statSync(payload).size > 25 * 1024 * 1024)
+                        throw new Error("oversized");
+                    bytes = fs.readFileSync(payload);
+                }
+                catch {
+                    throw new WebhookRefusal("invalid_event", "Supply a readable original payload file of at most 25 MiB.");
+                }
+                return acceptGithubWebhook(ctx.pm_root, { repo: ctx.args[0], delivery, event, signature,
+                    payload: bytes, secret: process.env.PM_GITHUB_WEBHOOK_SECRET ?? "" });
+            },
+        });
+        api.registerCommand({
+            name: "github webhook reconcile",
+            description: "Reconcile pending deliveries against current GitHub state into compact proposals, without changing items. Poll with github refresh for apply or recovery.",
+            arguments: [{ name: "owner/repo", required: true, description: "Expected repository boundary" }],
+            flags: [{ long: "--limit", value_name: "N", description: "Maximum deliveries per batch, 1 to 100 (default 20)" }],
+            async run(ctx) {
+                return reconcileGithubWebhooks(ctx.pm_root, ctx.args[0] ?? "", ctx.options.limit === undefined ? 20 : Number(ctx.options.limit));
+            },
+        });
         // command — legacy `pm gh-issues import <owner/repo>` (delegates to core)
         // -----------------------------------------------------------------------
         api.registerCommand({