pm-github 2026.10.16 → 2026.10.23

package/dist/index.js

@@ -14,13 +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 { 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, } 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";
@@ -109,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.
@@ -356,7 +365,7 @@ export function parseNextLink(linkHeader) {
 // Map a GitHub issue/PR state (+ optional stateReason) onto a pm status,
 // preserving `not_planned` closures as `canceled` rather than `closed`.
 export function mapState(state, stateReason) {
-    if (state === "closed" && stateReason === "not_planned")
+    if (state === "closed" && (stateReason === "not_planned" || stateReason === "duplicate"))
         return "canceled";
     return state === "closed" ? "closed" : "open";
 }
@@ -718,6 +727,7 @@ export function decodeCompletePmItems(parsed) {
         }
         ids.add(item.id);
         items.push({
+            ...item,
             id: item.id,
             title,
             status,
@@ -924,8 +934,9 @@ async function resolveAtomicSdkFunctions(opts) {
  * Derive an order-independent transaction id from the desired import state and
  * exact ordered mutation plan. Content or target changes produce a fresh
  * transaction; a reordered retry of the same plan resumes the durable journal.
+ * External history revisions distinguish a local edit from a retry of import-owned writes.
  */
-export function deriveAtomicTransactionId(repo, entries, mutations) {
+export function deriveAtomicTransactionId(repo, entries, mutations, contextVersions = []) {
     const canonical = [...entries]
         .sort((a, b) => a.issueNumber - b.issueNumber)
         .map((entry) => ({
@@ -938,8 +949,10 @@ export function deriveAtomicTransactionId(repo, entries, mutations) {
         tags: [...entry.tags].sort(),
         assignee: entry.assignee ?? null,
         milestone: entry.milestone ?? null,
+        fidelity: entry.fidelity ?? null,
+        linkOnly: entry.linkOnly ?? false,
     }));
-    const digest = crypto
+    const payload = crypto
         .createHash("sha256")
         .update(repo.toLowerCase())
         .update("\x1f")
@@ -948,10 +961,10 @@ export function deriveAtomicTransactionId(repo, entries, mutations) {
         // Recovery requires the exact ordered step plan. Include targets and
         // options so a changed id_prefix or provenance match gets a fresh journal
         // instead of colliding with an incompatible prior attempt.
-        .update(JSON.stringify(mutations))
-        .digest("hex")
-        .slice(0, 16);
-    return `${ATOMIC_IMPORT_PREFIX}${digest}`;
+        .update(JSON.stringify(mutations));
+    if (contextVersions.length > 0)
+        payload.update("\x1f").update(JSON.stringify([...contextVersions].sort()));
+    return `${ATOMIC_IMPORT_PREFIX}${payload.digest("hex").slice(0, 16)}`;
 }
 /** Stable create id keyed by the external GitHub issue, never by fetch order. */
 export function deriveAtomicItemId(repo, issueNumber, idPrefix, normalizeItemId) {
@@ -963,7 +976,14 @@ 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: { ...(!changed || changed.has("tags") ? { addTags: entry.tags } : {}), ...audit } }] };
+    }
     const sharedOptions = {
         title: entry.title,
         type: entry.itemType,
@@ -972,7 +992,14 @@ export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemI
         tags: entry.tags.join(","),
         ...(entry.assignee ? { assignee: entry.assignee } : {}),
         ...(entry.milestone ? { sprint: entry.milestone } : {}),
+        ...(entry.status === "canceled" ? { closeReason: entry.fidelity?.github_close_reason ?? `GitHub issue #${entry.issueNumber} closed` } : {}),
     };
+    // Explicit terminal reconciliation also handles canceled -> completed. The
+    // supported force option permits that source-authoritative repeat closure;
+    // finalization restores the real dates before the transaction commits.
+    const statusOptions = entry.status === "closed"
+        ? entry.fidelity ? { status: "closed", closeReason: entry.fidelity.github_close_reason, force: true } : {}
+        : { status: entry.status };
     const managedItemId = deriveAtomicItemId(repo, entry.issueNumber, idPrefix, normalizeItemId);
     // A missing match and a match at our deterministic external-key id use the
     // SAME create+update upsert plan. This is essential for crash recovery: if a
@@ -980,26 +1007,26 @@ 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",
                 id: managedItemId,
-                options: { ...sharedOptions, status: createStatus },
+                options: { ...sharedOptions, status: createStatus, message: `pm-github import create ${repo.toLowerCase()}#${entry.issueNumber}` },
             }, {
                 op: "update",
                 id: managedItemId,
                 options: {
                     ...sharedOptions,
-                    ...(entry.status !== "closed" ? { status: entry.status } : {}),
+                    ...statusOptions,
                 },
             }];
-        if (entry.status === "closed") {
+        if (entry.status === "closed" && !entry.fidelity) {
             mutations.push({
                 op: "close",
                 id: managedItemId,
                 reason: `GitHub issue #${entry.issueNumber} closed`,
-                // Preserve the source's real completion time instead of the import time.
+                // Legacy callers can supply completion directly; full plans finalize both lifecycle dates.
                 ...(entry.closedAt ? { options: { completedAt: entry.closedAt } } : {}),
             });
         }
@@ -1009,52 +1036,125 @@ export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemI
         };
     }
     const itemId = entry.match.id;
-    const updateOptions = { ...sharedOptions };
-    // close has a dedicated mutation so its reason is preserved. Every other
-    // transition (open/reopen/canceled) is safely reversible as part of update.
-    if (entry.status !== "closed") {
-        updateOptions.status = entry.status;
-    }
+    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,
             options: updateOptions,
         }];
-    if (entry.status === "closed") {
+    if (entry.status === "closed" && !entry.fidelity) {
         mutations.push({
             op: "close",
             id: itemId,
             reason: `GitHub issue #${entry.issueNumber} closed`,
-            // Preserve the source's real completion time instead of the import time.
+            // Legacy callers can supply completion directly; full plans finalize both lifecycle dates.
             ...(entry.closedAt ? { options: { completedAt: entry.closedAt } } : {}),
         });
     }
     return { itemId, mutations };
 }
-/** Commit a complete issue-import batch under one crash-resumable transaction. */
-export async function importGithubAtomic(pmRoot, repo, entries, opts = {}) {
-    const { commitItemMutations: commit, normalizeItemId, readSettings, } = await resolveAtomicSdkFunctions(opts);
-    let idPrefix = "pm-";
+/**
+ * Bind atomic plans to the latest external edit or different lifecycle generation.
+ * The importer's desired-state and compensation writes leave retries stable;
+ * local edits and later state cycles invalidate completed journals.
+ */
+async function importContextVersions(pmRoot, entries) {
+    const versions = [];
+    for (const entry of entries) {
+        if (!entry.fidelity || !entry.match?.id)
+            continue;
+        const snapshot = await sdkReadHistorySnapshot(sdkGetHistoryPath(pmRoot, entry.match.id), entry.match.id);
+        const context = snapshot.entries[selectImportContextIndex(snapshot.entries, entry.status)];
+        if (context)
+            versions.push(`${entry.match.id}:${crypto.createHash("sha256").update(JSON.stringify(context)).digest("hex")}`);
+    }
+    return versions;
+}
+/** 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 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.
+        return null;
     }
-    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);
-    }
-    const transactionId = deriveAtomicTransactionId(repo, entries, mutations);
+}
+/** 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), opts.updateOnly);
+        }
+    };
+    let committed = false;
     try {
         const result = await commit({
             pmRoot,
@@ -1066,7 +1166,14 @@ export async function importGithubAtomic(pmRoot, repo, entries, opts = {}) {
             // restores every UPDATE and CLOSE step (covered by the mixed rollback
             // integration test below this implementation).
             createCompensation: "delete",
+            onTransition: async (context) => {
+                if (context.transition === "committing")
+                    await finalize();
+                await opts.onTransition?.(context);
+            },
         });
+        committed = true;
+        await finalize();
         // A recovered journal may include work applied by the interrupted process
         // as well as steps resumed now. The SDK intentionally returns the durable
         // final results, not a per-invocation delta, so create/update counts cannot
@@ -1082,15 +1189,144 @@ 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(`${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(`${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);
         }
-        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);
+        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)
@@ -1895,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
@@ -2177,10 +2414,17 @@ 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) {
+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, opts.adoptCited === true);
+    match = identity.item;
+    const timeline = await fidelityContext.timeline(issue, repo, token);
+    const fidelity = buildImportFidelity(issue, fidelityContext.releases, timeline);
+    const targetStatus = mapState(issue.state, issue.state_reason);
+    const conflict = match?.status && match.status !== targetStatus && (["closed", "canceled"].includes(match.status) || issue.state === "closed")
+        ? { local: match.status, github: issue.state, rule: identity.linkOnly ? "preserve-provider-owner" : "github-source-wins" } : undefined;
     const kind = issue.pull_request ? "PR" : "issue";
     const labels = issue.labels.map((label) => label.name).filter(Boolean);
     const tag = provenanceTag(repo, issue.number);
@@ -2206,19 +2450,22 @@ async function prepareGithubImport(issue, repo, opts, token, match, fetchIssueCo
         issueNumber: issue.number,
         title,
         itemType: opts.itemType,
-        status: mapState(issue.state, issue.state_reason),
+        status: identity.linkOnly ? match.status : targetStatus,
         description: `GH ${kind} #${issue.number}: ${issue.html_url}` +
             (author ? ` · author @${author}` : "") +
             (issue.state_reason ? ` · state reason ${issue.state_reason}` : "") +
-            (issue.created_at ? ` · created ${issue.created_at}` : "") +
-            (issue.updated_at ? ` · updated ${issue.updated_at}` : ""),
+            ` · created ${issue.created_at} · updated ${issue.updated_at}`,
         body: writeCommentsToBody ? composeBody(issue, comments) : (issue.body || ""),
-        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,
         syncAnnotations,
         closedAt: issue.closed_at ?? undefined,
+        fidelity,
+        linkOnly: identity.linkOnly,
+        identity: { via: identity.via, ...(conflict ? { conflict } : {}) },
+        ...(identity.citation_candidates ? { citation_candidates: identity.citation_candidates } : {}),
         match,
     };
 }
@@ -2299,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)))
@@ -2311,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,
     };
 }
@@ -2442,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
@@ -2455,17 +2706,27 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
     // reported "would import N, skip 0" where the real run performs updates for
     // already-linked issues. A preview that overstates creates reads as "this will
     // duplicate my whole tracker" and is the one thing --dry-run exists to rule out.
-    const existingItems = (dependencies.readItems ?? readPmItems)(pmRoot);
+    /** Read the complete raw corpus in-process, retaining all provider metadata and bodies. */
+    const readImportItems = async () => {
+        if (dependencies.readItems)
+            return dependencies.readItems(pmRoot);
+        const corpus = certifyCompleteListResult(await listAllComplete({ includeBody: true }, { pmRoot, cwd: pmRoot, noExtensions: true }));
+        return decodeCompletePmItems(corpus);
+    };
+    const existingItems = await readImportItems();
     const existing = indexByProvenance(existingItems);
+    const fidelityContext = { items: existingItems, releases: readImportReleases(pmRoot),
+        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.
@@ -2473,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);
+            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;
@@ -2494,7 +2784,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         if (opts.gate && !opts.dryRun) {
             const preview = runCommandTrackerGate({ pmRoot, plannedItems: planned.map(entry => ({
                     itemId: entry.match?.id ?? `github-issue-${entry.issueNumber}`,
-                    fields: { title: entry.title, description: entry.description, body: entry.body, tags: entry.tags,
+                    fields: { ...entry.fidelity, title: entry.title, description: entry.description, body: entry.body, tags: entry.tags,
                         assignee: entry.assignee, sprint: entry.milestone,
                         comments: entry.syncAnnotations ? entry.comments.map(comment => ({
                             author: comment.user?.login, text: comment.body, created_at: comment.created_at,
@@ -2505,9 +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.`);
-    }
-    const gatePlanFields = opts.gate ? { gate: { completeness: gateCompleteness, idempotency: gateIdempotency, scan: "post-write" } } : {};
+                `${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.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,
+            ...(entry.citation_candidates ? { citation_candidates: entry.citation_candidates } : {}) };
+    });
+    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
@@ -2520,6 +2827,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                     dryRun: true,
                     wouldImport: 0,
                     wouldUpdate: 0,
+                    wouldAdopt: 0,
                     wouldSkip: skipped,
                     atomic: true,
                     ...fetchFields,
@@ -2529,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.`);
@@ -2543,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) } : {}),
@@ -2552,7 +2861,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         }
         const result = await (dependencies.commitAtomic ?? importGithubAtomic)(pmRoot, repo, prepared);
         if (opts.gate)
-            verifyImportedProvenance((dependencies.readItems ?? readPmItems)(pmRoot), prepared, repo);
+            verifyImportedProvenance(await readImportItems(), prepared, repo);
         // Planned native comments are part of the verified plan: a contended lock,
         // a refused add, or a committed entry whose created id is missing from the
         // post-commit routing map all leave planned comments unwritten, so they are
@@ -2589,58 +2898,63 @@ 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,
+            ...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);
+        // 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);
-        const { title, status, assignee, milestone, match, description, body, tags, comments, syncAnnotations, closedAt, } = prepared;
+        const { title, status, assignee, milestone, match, description, body, tags, comments, syncAnnotations, } = prepared;
         /**
          * Build the `pm close` argv for this issue's pm item.
          *
          * Two paths below close an item for the same reason — reconciling an
          * already-matched item whose upstream issue is now closed, and closing an
          * item that was just created `open` because pm-cli 2026.8.3 refuses a
-         * terminal `create --status closed`. Both must carry identical provenance
-         * (the reason) and identical completion evidence (GitHub's own `closed_at`,
-         * when it recorded one), so the argv is built once here rather than
-         * duplicated at each site where the two could silently drift apart.
+         * terminal `create --status closed`. Both carry the same source reason.
+         * Source completion is applied with source creation during finalization,
+         * avoiding an intermediate completion date before the SDK creation date.
          */
         const githubCloseArgs = (id) => {
-            const args = ["--path", pmRoot, "close", id, "--reason", `GitHub issue #${issue.number} closed`];
-            if (closedAt)
-                args.push("--completed-at", closedAt);
+            const args = ["--path", pmRoot, "close", id, "--reason", prepared.fidelity.github_close_reason];
             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++;
             continue;
         }
+        if (prepared.linkOnly) {
+            const ownerId = match.id;
+            const linked = pmRun(["--path", pmRoot, "update", ownerId, "--add-tags", tags.join(",")]);
+            if (!linked.ok)
+                throw new CommandError(`Could not link GitHub issue #${issue.number} to its existing owner.`);
+            await persistImportFidelity(pmRoot, ownerId, prepared.fidelity, true);
+            if (prepared.identity?.via === "citation")
+                adopted++;
+            else
+                updated++;
+            continue;
+        }
         if (match?.id) {
             // Idempotent update — never duplicate. Status transitions go through the
             // proper command (close requires a reason; reopen via update --status).
@@ -2663,17 +2977,22 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                 continue;
             }
             // Reconcile status separately.
+            if (status === "canceled" && match.status !== "canceled") {
+                const cancel = pmRun(["--path", pmRoot, "update", match.id, "--status", "canceled", "--close-reason", prepared.fidelity.github_close_reason]);
+                if (!cancel.ok)
+                    throw new CommandError(`Could not cancel GitHub issue #${issue.number}.`);
+            }
             if (status === "closed" && match.status !== "closed") {
                 // Close through `pm close` so the reason is real provenance; pass the
                 // source completion time as --completed-at when GitHub recorded one.
-                const close = pmRun(githubCloseArgs(match.id));
+                const close = pmRun([...githubCloseArgs(match.id), ...(match.status === "canceled" ? ["--force"] : [])]);
                 if (!close.ok) {
                     console.error(`#${issue.number}: close reconciliation failed — ${close.stderr}`);
                     skipped++;
                     continue;
                 }
             }
-            else if (status === "open" && match.status === "closed") {
+            else if (status === "open" && (match.status === "closed" || match.status === "canceled")) {
                 const reopen = pmRun(["--path", pmRoot, "update", match.id, "--status", "open", "--message", `GitHub issue #${issue.number} reopened`]);
                 if (!reopen.ok) {
                     console.error(`#${issue.number}: reopen reconciliation failed — ${reopen.stderr}`);
@@ -2684,7 +3003,11 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             if (syncAnnotations) {
                 commentWriteFailures += (await syncGithubCommentsToAnnotations(match.id, comments, pmRoot, issue.number)).failed;
             }
-            updated++;
+            await persistImportFidelity(pmRoot, match.id, prepared.fidelity, false);
+            if (prepared.identity?.via === "citation")
+                adopted++;
+            else
+                updated++;
             continue;
         }
         // A closed upstream issue cannot be born closed: governance
@@ -2703,21 +3026,22 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             "--tags", tags.join(","),
             "--message", `Imported from GitHub #${issue.number}`,
         ];
+        if (status === "canceled")
+            createArgs.push("--close-reason", prepared.fidelity.github_close_reason);
         if (assignee)
             createArgs.push("--assignee", assignee);
         if (milestone)
             createArgs.push("--sprint", milestone);
         // --json lets a following close (or annotations sync) address the freshly
         // created item by id without re-scanning the workspace.
-        if (mustClose || syncAnnotations)
-            createArgs.push("--json");
+        createArgs.push("--json");
         const created = pmRun(createArgs);
         if (!created.ok) {
             console.error(`#${issue.number}: create failed — ${created.stderr}`);
             skipped++;
             continue;
         }
-        const createdId = (mustClose || syncAnnotations) ? parseCreatedItemId(created.stdout) : undefined;
+        const createdId = parseCreatedItemId(created.stdout);
         if (mustClose) {
             if (createdId) {
                 const close = pmRun(githubCloseArgs(createdId));
@@ -2749,10 +3073,13 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                 commentWriteFailures += comments.length;
             }
         }
+        if (!createdId)
+            throw new CommandError(`Could not finalize GitHub issue #${issue.number}: created id missing.`);
+        await persistImportFidelity(pmRoot, createdId, prepared.fidelity, false);
         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.`);
@@ -2761,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
@@ -2784,9 +3112,9 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
     // Gated pipeline, phase 2 — the writes are on disk but nothing is committed or
     // pushed; scan the proposed tracker change now and fail closed.
     if (opts.gate)
-        verifyImportedProvenance((dependencies.readItems ?? readPmItems)(pmRoot), gatePlan, repo);
+        verifyImportedProvenance(await readImportItems(), gatePlan, repo);
     const gateReceipt = opts.gate ? gateImportWrites(pmRoot) : undefined;
-    return { imported, updated, skipped, ...fetchFields, ...depLinkResultFields(depLink), ...(gateReceipt ? { gate: gateReceipt } : {}) };
+    return { imported, updated, adopted, skipped, ...fetchFields, ...depLinkResultFields(depLink), ...planFields, ...(gateReceipt ? { gate: gateReceipt } : {}) };
 }
 /**
  * Emit the human-readable `--link-deps` summary to stderr.
@@ -4102,11 +4430,12 @@ function graphqlUrl() {
 // `errors` array, so we surface those explicitly. The combined user+org queries
 // below intentionally return a partial error for the wrong owner type while the
 // right one still resolves; we only throw when there is NO usable data.
-async function githubGraphQL(token, query, variables) {
+/** Execute a typed GraphQL request for internal import closure evidence. @internal */
+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);
     }
@@ -4876,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.
@@ -4896,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)" },
@@ -4977,7 +5307,7 @@ const PROJECT_SYNC_FLAGS = [
 const defineExtension = (module) => module;
 export default defineExtension({
     name: "pm-github",
-    version: "2026.10.16",
+    version: "2026.10.23",
     activate(api) {
         // -----------------------------------------------------------------------
         // schema — declare the GitHub provenance fields so the workspace knows them
@@ -4989,6 +5319,8 @@ export default defineExtension({
             { name: "github_author", type: "string", optional: true },
             { name: "github_created_at", type: "string", optional: true },
             { name: "github_updated_at", type: "string", optional: true },
+            { name: "github_link_only", type: "boolean", optional: true },
+            ...["github_closed_at", "github_state_reason", "github_close_reason", "github_release"].map(name => ({ name, type: "string", optional: true })),
         ]);
         // -----------------------------------------------------------------------
         // preflight — safe, local guard for mutating github commands. Scoped to
@@ -5006,6 +5338,7 @@ export default defineExtension({
         api.registerPreflight({
             commands: [
                 "github sync",
+                "github refresh",
                 "github export",
                 "github import",
                 "gh-issues import",
@@ -5187,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({
@@ -5311,6 +5726,7 @@ export default defineExtension({
                 { long: "--repo", value_name: "owner/repo", description: "Repository (or PM_GITHUB_REPO)" },
                 { long: "--pr", value_name: "n", repeatable: true, description: "Select a PR number (repeatable; conflicts with --since)" },
                 { long: "--since", value_name: "ISO date", description: "Select PRs merged at or after this ISO date/time" },
+                { long: "--required-checks", value_name: "contexts", description: "One required context per line when protection metadata is unavailable (spaces preserved; blank lines ignored)" },
                 { long: "--skip", value_name: "id", repeatable: true, description: "Never close this item (repeatable)" },
                 { long: "--apply", description: "Close eligible items (default: dry-run)" },
                 { long: "--dry-run", description: "Preview only; overrides --apply" },