pm-github 2026.10.27 → 2026.10.29

package/dist/index.js

@@ -1,10 +1,19 @@
+import { readGithubWorkspace, canonicalGithubStatus, githubStatusKind, githubStatusIsTerminal } from "./workspace.js";
 import { ownValue } from "./own-record.js";
+import { uniqueGithubLabelNames } from "./label-names.js";
+import { githubLabelsToTags, importTagArguments, importTagOptions, importTagValues, nativeTagAdditions } from "./import-tags.js";
+export { githubLabelsToTags } from "./import-tags.js";
 import { CloseoutUsageError, compactCloseoutReport, runCloseout } from "./closeout.js";
+import { readWorkflowFailure } from "./workflow-diagnostic.js";
 import { compileIssueForm, completeIssueForm, readRepositoryIssueForm, refuseIssueForm } from "./issue-forms.js";
 export { compileIssueForm, completeIssueForm, readRepositoryIssueForm } from "./issue-forms.js";
-import { AmbiguousCitationError, buildImportFidelity, fetchImportTimeline, importFidelityFields, matchImportedIssue, persistImportFidelity, readImportReleases, selectImportContextIndex, validateImportLifetime, } from "./import-fidelity.js";
+import { AmbiguousCitationError, buildImportFidelity, fetchImportTimeline, importFidelityFields, matchImportedIssue, normalizeImportValue, persistImportFidelity, readImportReleases, selectImportContextIndex, serializeImportTags, validateImportLifetime, } from "./import-fidelity.js";
 import { refreshChanges, runRefresh } from "./refresh.js";
 import { exploreGithubIdentities, planGithubIdentityRepair, applyGithubIdentityRepair } from "./identity.js";
+import { planGithubLabelMigration, readLabelMigrationJson } from "./labels.js";
+import { captureGithubDiscussion, refuseDiscussion } from "./discussions.js";
+export { captureGithubDiscussion, readGithubDiscussionComment, validateDiscussionCaptureReport } from "./discussions.js";
+export { planGithubLabelMigration, readGithubLabelCatalog, validateGithubLabelMigrationReport } from "./labels.js";
 export { exploreGithubIdentities, planGithubIdentityRepair, applyGithubIdentityRepair } from "./identity.js";
 import { acceptGithubWebhook, reconcileGithubWebhooks, WebhookRefusal } from "./webhooks.js";
 export { acceptGithubWebhook, reconcileGithubWebhooks, WebhookRefusal } from "./webhooks.js";
@@ -14,7 +23,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-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 { createPmCliExpectedError, comments as pmCommentsFn, commitItemMutations as sdkCommitItemMutations, isExternalDependencyReference, listAllComplete, certifyCompleteListResult, listAllItemMetadata as sdkListAllItemMetadata, normalizeItemId as sdkNormalizeItemId, readSettings as sdkReadSettings, resolvePmRoot as sdkResolvePmRoot, toImportTags, 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";
@@ -324,7 +333,7 @@ async function request(method, url, token, payload, maxRetries = 4) {
             attempt++;
             continue;
         }
-        throw new Error(`GitHub API returned HTTP ${res.status}`);
+        throw new Error(`GitHub API returned HTTP ${res.status} for ${method} ${new URL(url).pathname}`);
     }
 }
 /** Fetch a single GitHub REST endpoint via GET and return the decoded
@@ -423,18 +432,7 @@ export function parseLabelMap(options, ...keys) {
 // map to the same GitHub label are collapsed (GitHub rejects duplicate labels
 // on an issue with a 422), preserving first-seen order.
 export function applyLabelMap(labels, labelMap) {
-    if (!labelMap || labelMap.size === 0)
-        return labels;
-    const out = [];
-    const seen = new Set();
-    for (const label of labels) {
-        const mapped = labelMap.get(label) ?? label;
-        if (seen.has(mapped))
-            continue;
-        seen.add(mapped);
-        out.push(mapped);
-    }
-    return out;
+    return uniqueGithubLabelNames(labels.map(label => labelMap?.get(label) ?? label));
 }
 // Parse one or more CSV-like option values into a deduplicated string list.
 // Accepts a single string ("a,b") or repeated values (["a,b", "c"]).
@@ -964,29 +962,30 @@ 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, updateOnly = false) {
+export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemId, updateOnly = false, statuses) {
     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 closing = canonicalGithubStatus(entry.status, statuses) === canonicalGithubStatus("closed", statuses);
+    const changed = updateOnly ? new Set(refreshChanges(entry, statuses).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 } }] };
+        return { itemId: entry.match.id, mutations: [{ op: "update", id: entry.match.id, options: { ...(!changed || changed.has("tags") ? importTagOptions(entry) : {}), ...audit } }] };
     }
     const sharedOptions = {
         title: entry.title,
         type: entry.itemType,
         description: entry.description,
         body: entry.body,
-        tags: entry.tags.join(","),
+        ...importTagOptions(entry),
         ...(entry.assignee ? { assignee: entry.assignee } : {}),
         ...(entry.milestone ? { sprint: entry.milestone } : {}),
-        ...(entry.status === "canceled" ? { closeReason: entry.fidelity?.github_close_reason ?? `GitHub issue #${entry.issueNumber} closed` } : {}),
+        ...((!closing && githubStatusIsTerminal(entry.status, statuses)) ? { 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 } : {}
+    const statusOptions = closing
+        ? entry.fidelity ? { status: entry.status, 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
@@ -996,7 +995,7 @@ export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemI
     // create step treats an existing stable id as already applied; update then
     // makes later content-bearing transactions refresh the item normally.
     if (!updateOnly && (!entry.match?.id || entry.match.id === managedItemId)) {
-        const createStatus = entry.status === "closed" ? "open" : entry.status;
+        const createStatus = closing ? "open" : entry.status;
         const mutations = [{
                 op: "create",
                 id: managedItemId,
@@ -1009,7 +1008,7 @@ export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemI
                     ...statusOptions,
                 },
             }];
-        if (entry.status === "closed" && !entry.fidelity) {
+        if (closing && !entry.fidelity) {
             mutations.push({
                 op: "close",
                 id: managedItemId,
@@ -1027,7 +1026,7 @@ export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemI
     const updateOptions = {
         ...(updateOnly ? {
             ...(changed.has("title") ? { title: entry.title } : {}),
-            ...(changed.has("tags") ? { tags: entry.tags.join(",") } : {}),
+            ...(changed.has("tags") ? importTagOptions(entry) : {}),
             ...(changed.has("status") && sharedOptions.closeReason !== undefined ? { closeReason: sharedOptions.closeReason } : {}),
         } : sharedOptions), ...(!changed || changed.has("status") ? statusOptions : {}), ...audit,
     };
@@ -1036,7 +1035,7 @@ export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemI
             id: itemId,
             options: updateOptions,
         }];
-    if (entry.status === "closed" && !entry.fidelity) {
+    if (closing && !entry.fidelity) {
         mutations.push({
             op: "close",
             id: itemId,
@@ -1052,13 +1051,13 @@ export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemI
  * 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) {
+async function importContextVersions(pmRoot, entries, statuses) {
     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)];
+        const context = snapshot.entries[selectImportContextIndex(snapshot.entries, entry.status, statuses)];
         if (context)
             versions.push(`${entry.match.id}:${crypto.createHash("sha256").update(JSON.stringify(context)).digest("hex")}`);
     }
@@ -1203,6 +1202,7 @@ async function commitGithubImportTransaction(config) {
 export async function importGithubAtomic(pmRoot, repo, entries, opts = {}) {
     pmRoot = sdkResolvePmRoot(process.cwd(), pmRoot);
     const { commitItemMutations: commit, normalizeItemId, readSettings, } = await resolveAtomicSdkFunctions(opts);
+    const workspace = await readGithubWorkspace(pmRoot);
     let idPrefix = "pm-";
     try {
         const settings = await readSettings(pmRoot);
@@ -1219,11 +1219,11 @@ export async function importGithubAtomic(pmRoot, repo, entries, opts = {}) {
     // 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);
+        const planned = buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemId, opts.updateOnly, workspace.statuses);
         itemIds.set(entry.issueNumber, planned.itemId);
         mutations.push(...planned.mutations);
     }
-    const transactionId = deriveAtomicTransactionId(repo, entries, mutations, await importContextVersions(pmRoot, entries));
+    const transactionId = deriveAtomicTransactionId(repo, entries, mutations, await importContextVersions(pmRoot, entries, workspace.statuses));
     // 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
@@ -2411,7 +2411,7 @@ export async function prepareGithubImport(issue, repo, opts, token, match, fetch
     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")
+    const conflict = match?.status && canonicalGithubStatus(match.status, fidelityContext.statuses) !== canonicalGithubStatus(targetStatus, fidelityContext.statuses) && (githubStatusIsTerminal(match.status, fidelityContext.statuses) || 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);
@@ -2444,7 +2444,7 @@ export async function prepareGithubImport(issue, repo, opts, token, match, fetch
             (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 || identity.via === "citation" ? match.tags ?? [] : []), ...labels, tag, ...(ghAuthorTag ? [ghAuthorTag] : [])])],
+        tags: toImportTags([...(identity.linkOnly || identity.via === "citation" ? match.tags ?? [] : []), ...githubLabelsToTags([...labels, tag, ...(ghAuthorTag ? [ghAuthorTag] : [])])]),
         assignee: issue.assignee?.login,
         milestone: issue.milestone?.title,
         comments,
@@ -2457,6 +2457,16 @@ export async function prepareGithubImport(issue, repo, opts, token, match, fetch
         match,
     };
 }
+/** Recognize a complete source projection without treating the SDK mutation clock as content. */
+export function importEntryUnchanged(entry, types, statuses) {
+    if (!entry.match?.id || !entry.fidelity || refreshChanges(entry, statuses).length !== 0)
+        return false;
+    if (entry.linkOnly)
+        return true;
+    const fields = { type: entry.itemType, description: entry.description, body: entry.body,
+        ...(entry.assignee ? { assignee: entry.assignee } : {}), ...(entry.milestone ? { sprint: entry.milestone } : {}) };
+    return Object.entries(fields).every(([field, value]) => normalizeImportValue(field, ownValue(entry.match, field) ?? "", types, statuses) === normalizeImportValue(field, value, types, statuses));
+}
 /**
  * Verify that a gated import's plan accounts for every fetched issue exactly once.
  *
@@ -2534,11 +2544,11 @@ 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)))
+            if (entry.identity?.via === "citation" && !importTagValues(entry).includes(provenanceTag(repo, entry.issueNumber)))
                 untaggedNewEntries++;
             continue;
         }
-        if (!entry.tags.includes(provenanceTag(repo, entry.issueNumber)))
+        if (!importTagValues(entry).includes(provenanceTag(repo, entry.issueNumber)))
             untaggedNewEntries++;
     }
     const conflictingTargets = matchedIds.length - new Set(matchedIds).size;
@@ -2628,11 +2638,11 @@ function gateImportWrites(pmRoot) {
  * throws {@link CommandError} (with a semantic exit code) on failure.
  *
  * @param repoArg - The `owner/repo` to import from.
- * @param pmRoot - Workspace root or pm data dir.
+ * @param pmPath - Workspace root or pm data dir.
  * @param opts - Normalized import options.
  * @param deps - Injectable collaborators (token resolver, fetchers, etc.) for tests.
  */
-export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
+export async function runImport(repoArg, pmPath, opts, dependencies = {}) {
     if (!repoArg || !repoArg.includes("/")) {
         throw new CommandError("Usage: pm github import <owner/repo> [--all|--state open|closed|all] " +
             "[--labels bug,enhancement] [--since <iso>] [--assignee <login>] " +
@@ -2674,7 +2684,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         console.error("No issues found.");
         // Even a no-op gated import must prove the workspace is gateable (a Git work
         // tree the scanner can read), so the empty-change gate scan runs here too.
-        const emptyGateReceipt = opts.gate && !opts.dryRun ? gateImportWrites(pmRoot) : undefined;
+        const emptyGateReceipt = opts.gate && !opts.dryRun ? gateImportWrites(pmPath) : undefined;
         if (opts.dryRun && (opts.atomic || missingIssues.length > 0)) {
             return {
                 dryRun: true,
@@ -2694,6 +2704,8 @@ 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 workspace = await readGithubWorkspace(pmPath);
+    const pmRoot = workspace.pmRoot;
     /** Read the complete raw corpus in-process, retaining all provider metadata and bodies. */
     const readImportItems = async () => {
         if (dependencies.readItems)
@@ -2703,7 +2715,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
     };
     const existingItems = await readImportItems();
     const existing = indexByProvenance(existingItems);
-    const fidelityContext = { items: existingItems, releases: readImportReleases(pmRoot),
+    const fidelityContext = { statuses: workspace.statuses, items: existingItems, releases: readImportReleases(pmRoot),
         timeline: dependencies.fetchIssueTimeline ?? (dependencies.fetchIssues ? async () => [] : fetchImportTimeline) };
     let imported = 0;
     let updated = 0;
@@ -2847,7 +2859,14 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                 ...fetchFields,
             };
         }
-        const result = await (dependencies.commitAtomic ?? importGithubAtomic)(pmRoot, repo, prepared);
+        // Mixed create/update batches can select a fresh journal after the first
+        // apply. Replaying an otherwise identical SDK UPDATE advances updated_at.
+        // Never hide an interrupted journal behind the unchanged-state shortcut.
+        const typeNames = new Map(Object.entries(workspace.types.alias_to_type));
+        const unchanged = prepared.every(entry => importEntryUnchanged(entry, typeNames, workspace.statuses)) && (await listUnfinishedGithubImports(pmRoot)).length === 0;
+        const result = unchanged ? { transactionId: undefined, recovered: false, recoveredItems: undefined, imported: 0, updated: 0,
+            itemIds: new Map(prepared.map(entry => [entry.issueNumber, entry.match.id])) }
+            : await (dependencies.commitAtomic ?? importGithubAtomic)(pmRoot, repo, prepared);
         if (opts.gate)
             verifyImportedProvenance(await readImportItems(), prepared, repo);
         // Planned native comments are part of the verified plan: a contended lock,
@@ -2867,7 +2886,9 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             }
         }
         failClosedOnPlanDivergence(opts.gate, skipped, skipped, commentWriteFailures);
-        if (result.recovered) {
+        if (unchanged)
+            console.error("Atomic import unchanged; no item transaction was needed.");
+        else if (result.recovered) {
             console.error(`Atomic import recovered transaction ${result.transactionId} covering ${result.recoveredItems ?? prepared.length} item(s).`);
         }
         else {
@@ -2884,6 +2905,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         const gateReceipt = opts.gate ? gateImportWrites(pmRoot) : undefined;
         return {
             transactionId: result.transactionId,
+            ...(unchanged ? { unchanged: true } : {}),
             recovered: result.recovered,
             imported: result.imported,
             updated: result.updated - (result.recovered ? 0 : adoptionCount),
@@ -2904,7 +2926,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             continue;
         }
         const labels = issue.labels.map((l) => l.name).filter(Boolean);
-        const { title, status, assignee, milestone, match, description, body, tags, comments, syncAnnotations, } = prepared;
+        const { title, status, assignee, milestone, match, description, body, comments, syncAnnotations, } = prepared;
         /**
          * Build the `pm close` argv for this issue's pm item.
          *
@@ -2933,7 +2955,9 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         }
         if (prepared.linkOnly) {
             const ownerId = match.id;
-            const linked = pmRun(["--path", pmRoot, "update", ownerId, "--add-tags", tags.join(",")]);
+            const nativeTags = importTagArguments(prepared);
+            const linked = nativeTags.length
+                ? pmRun(["--path", pmRoot, "update", ownerId, ...nativeTags]) : { ok: true };
             if (!linked.ok)
                 throw new CommandError(`Could not link GitHub issue #${issue.number} to its existing owner.`);
             await persistImportFidelity(pmRoot, ownerId, prepared.fidelity, true);
@@ -2946,12 +2970,13 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         if (match?.id) {
             // Idempotent update — never duplicate. Status transitions go through the
             // proper command (close requires a reason; reopen via update --status).
+            const nativeTags = importTagArguments(prepared);
             const updArgs = [
                 "--path", pmRoot, "update", match.id,
                 "--title", title,
                 "--description", description,
                 "--body", body,
-                "--tags", tags.join(","),
+                ...nativeTags,
                 "--message", `Re-imported from GitHub #${issue.number}`,
             ];
             if (assignee)
@@ -2965,22 +2990,22 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                 continue;
             }
             // Reconcile status separately.
-            if (status === "canceled" && match.status !== "canceled") {
+            if (canonicalGithubStatus(status, workspace.statuses) === canonicalGithubStatus("canceled", workspace.statuses) && canonicalGithubStatus(match.status, workspace.statuses) !== canonicalGithubStatus("canceled", workspace.statuses)) {
                 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") {
+            if (canonicalGithubStatus(status, workspace.statuses) === canonicalGithubStatus("closed", workspace.statuses) && canonicalGithubStatus(match.status, workspace.statuses) !== canonicalGithubStatus("closed", workspace.statuses)) {
                 // 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), ...(match.status === "canceled" ? ["--force"] : [])]);
+                const close = pmRun([...githubCloseArgs(match.id), ...(githubStatusIsTerminal(match.status, workspace.statuses) ? ["--force"] : [])]);
                 if (!close.ok) {
                     console.error(`#${issue.number}: close reconciliation failed — ${close.stderr}`);
                     skipped++;
                     continue;
                 }
             }
-            else if (status === "open" && (match.status === "closed" || match.status === "canceled")) {
+            else if (canonicalGithubStatus(status, workspace.statuses) === canonicalGithubStatus("open", workspace.statuses) && githubStatusIsTerminal(match.status, workspace.statuses)) {
                 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}`);
@@ -3002,8 +3027,8 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         // `require_close_reason` rejects `pm create --status closed`. Create the
         // item open, then close it through `pm close` with the source's real
         // completion timestamp (`closed_at`) as --completed-at provenance.
-        const createStatus = status === "closed" ? "open" : status;
-        const mustClose = status === "closed";
+        const createStatus = canonicalGithubStatus(status, workspace.statuses) === canonicalGithubStatus("closed", workspace.statuses) ? "open" : status;
+        const mustClose = canonicalGithubStatus(status, workspace.statuses) === canonicalGithubStatus("closed", workspace.statuses);
         const createArgs = [
             "--path", pmRoot, "create",
             "--title", title,
@@ -3011,10 +3036,10 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             "--status", createStatus,
             "--description", description,
             "--body", body,
-            "--tags", tags.join(","),
+            "--tags", importTagOptions(prepared).tags,
             "--message", `Imported from GitHub #${issue.number}`,
         ];
-        if (status === "canceled")
+        if (canonicalGithubStatus(status, workspace.statuses) === canonicalGithubStatus("canceled", workspace.statuses))
             createArgs.push("--close-reason", prepared.fidelity.github_close_reason);
         if (assignee)
             createArgs.push("--assignee", assignee);
@@ -3166,8 +3191,8 @@ function failClosedOnPlanDivergence(gate, plannedSkipped, actualSkipped, comment
 // ---------------------------------------------------------------------------
 // Sync core — push pm status changes back to GitHub (close / reopen)
 // ---------------------------------------------------------------------------
-function pmStatusToGithubState(status) {
-    return status === "closed" || status === "canceled" ? "closed" : "open";
+function pmStatusToGithubState(status, statuses) {
+    return githubStatusIsTerminal(status, statuses) ? "closed" : "open";
 }
 /**
  * Require every requested item before a remote sync or export can begin.
@@ -3185,7 +3210,7 @@ function requireRequestedItems(items, requested) {
 }
 // Build the pm → GitHub issue sync plan: for each pm item linked to `repo`, emit
 // a create-or-update entry keyed by the issue's provenance tag.
-export function planSync(items, repo) {
+export function planSync(items, repo, statuses) {
     const plan = [];
     const repoLc = repo.toLowerCase();
     for (const item of items) {
@@ -3195,7 +3220,7 @@ export function planSync(items, repo) {
             const p = parseProvenanceTag(tag);
             if (!p || p.repo !== repoLc)
                 continue;
-            const desired = pmStatusToGithubState(item.status);
+            const desired = pmStatusToGithubState(item.status, statuses);
             plan.push({
                 id: item.id,
                 number: p.number,
@@ -3230,7 +3255,8 @@ async function runSync(ctx) {
             "(set GITHUB_TOKEN/GH_TOKEN or run `gh auth login`). Use --dry-run to preview without a token.", EXIT_CODE.USAGE);
     }
     const selected = requireRequestedItems(readPmItems(ctx.pm_root), scopedIds);
-    const plan = planSync(selected, repo);
+    const workspace = await readGithubWorkspace(ctx.pm_root);
+    const plan = planSync(selected, repo, workspace.statuses);
     if (plan.length === 0) {
         const scopeNote = scopedIds.length > 0 ? ` from --ids (${scopedIds.join(", ")})` : "";
         console.error(`No pm items${scopeNote} linked to ${repo} ` +
@@ -3292,7 +3318,7 @@ async function runSync(ctx) {
 }
 // Convert a pm item into the GitHub issue create/update payload, dropping
 // internal provenance tags from labels and applying the optional label map.
-function itemToGithubPayload(item, labelMap) {
+function itemToGithubPayload(item, labelMap, statuses) {
     // Drop our internal provenance tags from exported labels, then apply any
     // user-supplied label mapping (pm tag → GitHub label). Both issue provenance
     // (`gh:owner/repo#N`) and project provenance (`gh-project:owner/number#itemId`)
@@ -3303,18 +3329,18 @@ function itemToGithubPayload(item, labelMap) {
         title: item.title ?? "(untitled)",
         body: item.body || item.description || "",
         labels: applyLabelMap(labels, labelMap),
-        state: item.status === "closed" || item.status === "canceled" ? "closed" : "open",
+        state: pmStatusToGithubState(item.status, statuses),
     };
 }
 // Build the create/update plan. `repo` (lowercased) decides which provenance
 // tags count as an "already exported to THIS repo" link → update; everything
 // else is a create. Pure + side-effect free so it can be unit-tested and
 // printed verbatim in --dry-run.
-export function buildExportPlan(items, repo, labelMap) {
+export function buildExportPlan(items, repo, labelMap, statuses) {
     const repoLc = repo?.toLowerCase();
     const plan = [];
     for (const item of items) {
-        const payload = itemToGithubPayload(item, labelMap);
+        const payload = itemToGithubPayload(item, labelMap, statuses);
         let number;
         if (repoLc) {
             for (const tag of item.tags ?? []) {
@@ -3368,11 +3394,11 @@ export async function applyExportPlan(plan, repo, token, requestFn) {
                 throw new Error("update entry is missing its GitHub issue number");
             }
             if (entry.action === "update" && entry.number !== undefined) {
-                await requestFn("PATCH", `${githubApiBase()}/repos/${repo}/issues/${entry.number}`, token, JSON.stringify({ title: p.title, body: p.body, labels: p.labels, state: p.state }));
+                await requestFn("PATCH", `${githubApiBase()}/repos/${repo}/issues/${entry.number}`, token, JSON.stringify({ title: p.title, body: p.body, labels: uniqueGithubLabelNames(p.labels), state: p.state }));
                 updated++;
             }
             else {
-                await requestFn("POST", `${githubApiBase()}/repos/${repo}/issues`, token, JSON.stringify({ title: p.title, body: p.body, labels: p.labels }));
+                await requestFn("POST", `${githubApiBase()}/repos/${repo}/issues`, token, JSON.stringify({ title: p.title, body: p.body, labels: uniqueGithubLabelNames(p.labels) }));
                 created++;
             }
         }
@@ -3476,10 +3502,11 @@ async function runExport(ctx) {
     else if (["form-ref", "formRef", "form-answers", "formAnswers", "form-bindings", "formBindings"].some(flag => optionProvided(options, flag))) {
         refuseIssueForm("invalid_form_input", [{ field: "form", reason: "selection", remedy: "Pass --form with --repo and --form-ref to enforce an issue-form contract." }]);
     }
-    const plan = buildExportPlan(selected, repo, labelMap);
+    const workspace = await readGithubWorkspace(ctx.pm_root);
+    const plan = buildExportPlan(selected, repo, labelMap, workspace.statuses);
     for (const [index, completion] of completions.entries()) {
         plan[index].payload.body = completion.body;
-        plan[index].payload.labels = [...new Set([...plan[index].payload.labels, ...completion.report.contract.labels])];
+        plan[index].payload.labels = uniqueGithubLabelNames([...plan[index].payload.labels, ...completion.report.contract.labels]);
     }
     const creates = plan.filter((e) => e.action === "create").length;
     const updates = plan.filter((e) => e.action === "update").length;
@@ -3739,11 +3766,11 @@ function isGithubBlockerDependency(target) {
  * @param items - The complete runtime-validated item corpus.
  * @returns The candidate items, in corpus order.
  */
-export function selectBlockerCandidates(items) {
+export function selectBlockerCandidates(items, statuses) {
     return items.filter((item) => {
-        if (item.status === "blocked")
+        if (githubStatusKind(item.status, statuses) === "blocked")
             return true;
-        if (BLOCKER_TERMINAL_STATUSES.has(item.status))
+        if (githubStatusIsTerminal(item.status, statuses))
             return false;
         return (item.dependencies.some((dep) => dep.kind === "blocked_by" && isGithubBlockerDependency(dep.id))
             || (item.blockedBy !== undefined && isGithubBlockerDependency(item.blockedBy)));
@@ -4202,7 +4229,8 @@ async function runBlockers(ctx) {
     }
     const corpus = await readBlockerPmItems(ctx.pm_root);
     const selected = requireRequestedItems(corpus, scopedIds);
-    const candidates = selectBlockerCandidates(selected);
+    const workspace = await readGithubWorkspace(ctx.pm_root);
+    const candidates = selectBlockerCandidates(selected, workspace.statuses);
     const perItem = candidates.map((item) => ({ item, references: collectBlockerReferences(item, fallbackRepo) }));
     const unique = new Map();
     for (const entry of perItem) {
@@ -4848,7 +4876,8 @@ async function runProjectImport(ctx) {
     // Reading the local store is non-mutating and keeps dry-run faithful: linked
     // project items must preview as updates, not misleading duplicate creates.
     const pmItems = readPmItems(ctx.pm_root);
-    const plan = buildProjectImportPlan(projectItems, ref, pmItems, statusMap);
+    const workspace = await readGithubWorkspace(ctx.pm_root);
+    const plan = buildProjectImportPlan(projectItems, ref, pmItems, statusMap, workspace.statuses);
     let imported = 0;
     let updated = 0;
     let skipped = 0;
@@ -4863,11 +4892,12 @@ async function runProjectImport(ctx) {
             continue;
         }
         if (entry.action === "update" && entry.pmId) {
+            const addedTags = nativeTagAdditions(pmItems.find(item => item.id === entry.pmId).tags, entry.tags);
             const updArgs = [
                 "--path", ctx.pm_root, "update", entry.pmId,
                 "--title", entry.title,
                 "--description", description,
-                "--tags", entry.tags.join(","),
+                ...(addedTags.length ? ["--add-tags", addedTags.join(",")] : []),
                 "--message", `Re-imported from GitHub project ${ref.owner}/${ref.number}`,
             ];
             if (entry.body)
@@ -4880,9 +4910,12 @@ async function runProjectImport(ctx) {
             // A `closed` mapping cannot go through `pm update --status closed`
             // (governance require_close_reason rejects it since pm-cli 2026.8.3);
             // the update omits --status and a separate `pm close` records the reason.
-            const closeAfterUpdate = entry.mappedStatus === "closed";
-            if (entry.mappedStatus && !closeAfterUpdate)
+            const closeAfterUpdate = entry.mappedStatus !== undefined && canonicalGithubStatus(entry.mappedStatus, workspace.statuses) === workspace.statuses.close_status;
+            if (entry.mappedStatus && !closeAfterUpdate) {
                 updArgs.push("--status", entry.mappedStatus);
+                if (githubStatusIsTerminal(entry.mappedStatus, workspace.statuses))
+                    updArgs.push("--close-reason", projectImportCloseReason(ref, entry.content));
+            }
             const upd = pmRun(updArgs);
             if (!upd.ok) {
                 console.error(`  ${entry.title}: update failed — ${upd.stderr}`);
@@ -4904,19 +4937,21 @@ async function runProjectImport(ctx) {
         // `require_close_reason` rejects `pm create --status closed` (pm-cli
         // 2026.8.3+). Create open, then close through `pm close` with factual
         // provenance. `--json` is needed to read the assigned id for the close.
-        const createStatus = entry.status === "closed" ? "open" : entry.status;
-        const mustClose = entry.status === "closed";
+        const mustClose = canonicalGithubStatus(entry.status, workspace.statuses) === workspace.statuses.close_status;
+        const createStatus = mustClose ? workspace.statuses.open_status : entry.status;
         const createArgs = [
             "--path", ctx.pm_root, "create",
             "--title", entry.title,
             "--type", itemType,
             "--status", createStatus,
             "--description", description,
-            "--tags", entry.tags.join(","),
+            "--tags", serializeImportTags(entry.tags),
             "--message", `Imported from GitHub project ${ref.owner}/${ref.number}`,
         ];
         if (entry.body)
             createArgs.push("--body", entry.body);
+        if (!mustClose && githubStatusIsTerminal(entry.status, workspace.statuses))
+            createArgs.push("--close-reason", projectImportCloseReason(ref, entry.content));
         if (mustClose)
             createArgs.push("--json");
         const created = pmRun(createArgs);
@@ -4991,10 +5026,10 @@ async function applyPushEntry(entry, meta, ref, pmById, pmRoot, token) {
         if (pm?.id) {
             const tag = projectItemTag(ref, itemId);
             const existingTags = pm.tags;
-            if (!existingTags.includes(tag)) {
+            if (nativeTagAdditions(existingTags, [tag]).length) {
                 const upd = pmRun([
                     "--path", pmRoot, "update", pm.id,
-                    "--tags", [...existingTags, tag].join(","),
+                    "--add-tags", tag,
                     "--message", `Linked to GitHub project ${ref.owner}/${ref.number}`,
                 ]);
                 if (!upd.ok)
@@ -5037,22 +5072,22 @@ async function applyPushEntry(entry, meta, ref, pmById, pmRoot, token) {
  * @param pmRoot - Workspace root for the `pm` invocation.
  * @returns The argv array.
  */
-export function buildPullEntryArgs(entry, pmRoot) {
+export function buildPullEntryArgs(entry, pmRoot, statuses) {
     const reason = `GitHub project status → ${entry.toStatus}`;
-    if (entry.toStatus === "closed") {
+    if (canonicalGithubStatus(entry.toStatus, statuses) === (statuses?.close_status ?? "closed")) {
         return ["--path", pmRoot, "close", entry.pmId, "--reason", reason];
     }
-    if (entry.toStatus === "canceled") {
+    if (githubStatusIsTerminal(entry.toStatus, statuses)) {
         return [
             "--path", pmRoot, "update", entry.pmId,
-            "--status", "canceled",
+            "--status", canonicalGithubStatus(entry.toStatus, statuses),
             "--close-reason", reason,
             "--message", reason,
         ];
     }
     return [
         "--path", pmRoot, "update", entry.pmId,
-        "--status", entry.toStatus,
+        "--status", canonicalGithubStatus(entry.toStatus, statuses),
         "--message", reason,
     ];
 }
@@ -5060,8 +5095,8 @@ export function buildPullEntryArgs(entry, pmRoot) {
 // (records closed_at + close_reason); `canceled` keeps its distinct terminal
 // state via `pm update` while recording `--close-reason`; everything else is a
 // plain `pm update --status`.
-function applyPullEntry(entry, pmRoot) {
-    const res = pmRun(buildPullEntryArgs(entry, pmRoot));
+function applyPullEntry(entry, pmRoot, statuses) {
+    const res = pmRun(buildPullEntryArgs(entry, pmRoot, statuses));
     return res.ok ? { changed: true } : { changed: false, error: res.stderr };
 }
 /**
@@ -5110,11 +5145,12 @@ async function runProjectSync(ctx) {
     for (const it of scoped.selected)
         if (it.id)
             pmById.set(it.id, it);
+    const workspace = await readGithubWorkspace(ctx.pm_root);
     const pushPlan = doPush
-        ? buildProjectPushPlan(scoped.selected, ref, projectItems, meta.statusField, { addMissing, statusMap })
+        ? buildProjectPushPlan(scoped.selected, ref, projectItems, meta.statusField, { addMissing, statusMap, statuses: workspace.statuses })
         : undefined;
     const pullPlan = doPull
-        ? buildProjectPullPlan(scoped.selected, ref, projectItems, statusMap)
+        ? buildProjectPullPlan(scoped.selected, ref, projectItems, statusMap, workspace.statuses)
         : undefined;
     // Conflict resolution when applying BOTH directions: a linked item can appear
     // in both plans. `--prefer pm` (default) lets push win (skip its pull entry);
@@ -5181,7 +5217,7 @@ async function runProjectSync(ctx) {
         for (const e of pullActionable) {
             if (prefer === "pm" && pushItemIds.has(e.itemId))
                 continue; // push wins
-            const r = applyPullEntry(e, ctx.pm_root);
+            const r = applyPullEntry(e, ctx.pm_root, workspace.statuses);
             if (!r.changed) {
                 console.error(`  pull ${e.pmId} "${e.title}": ${r.error}`);
                 pullFailed++;
@@ -5317,7 +5353,7 @@ const PROJECT_SYNC_FLAGS = [
 const defineExtension = (module) => module;
 export default defineExtension({
     name: "pm-github",
-    version: "2026.10.27",
+    version: "2026.10.29",
     activate(api) {
         // -----------------------------------------------------------------------
         // schema — declare the GitHub provenance fields so the workspace knows them
@@ -5577,6 +5613,52 @@ export default defineExtension({
                 });
             },
         });
+        api.registerCommand({
+            name: "github discussion capture",
+            description: "Preview explicitly marked issue-comment spans as native Decisions. Apply only the reviewed digest; source instructions remain quoted data.",
+            flags: [
+                { long: "--input", value_name: "file", description: "Strict JSON selection: repo, issue, item, selections with comment/start/end/quote/marked:true" },
+                { long: "--approve", value_name: "digest", description: "Apply the exact reviewed preview, re-reading every source and native target" },
+                { long: "--max-output-bytes", value_name: "N", description: "Complete JSON receipt budget, integer 1024..131072 (default 65536)" },
+            ],
+            async run(ctx) {
+                const { input, approve, maxOutputBytes } = ctx.options;
+                if (typeof input !== "string" || approve !== undefined && typeof approve !== "string")
+                    refuseDiscussion("invalid_selection", "Supply --input with a strict JSON selection document and an optional full --approve digest.");
+                let selection;
+                try {
+                    selection = readLabelMigrationJson(input);
+                }
+                catch {
+                    refuseDiscussion("invalid_selection", "Supply a readable bounded regular JSON selection file; see pm github discussion capture --help.");
+                }
+                return captureGithubDiscussion(ctx.pm_root, selection, ctx.sdk, {
+                    approval: approve, maxOutputBytes: maxOutputBytes === undefined ? undefined : Number(maxOutputBytes),
+                });
+            },
+        });
+        api.registerCommand({
+            name: "github labels plan",
+            description: "Preview exact provider label rename/consolidation impacts on stored tags and declared filters/mappings. Read-only; --approve revalidates a saved digest against current state.",
+            flags: [
+                { long: "--input", value_name: "file", description: "Strict JSON request with repo, source IDs/names, change, filters, mappings and choices" },
+                { long: "--catalog", value_name: "file", description: "Complete offline catalog JSON; omit to fetch all current GitHub labels" },
+                { long: "--approve", value_name: "digest", description: "Check the exact reviewed plan against current labels, policy and SDK revisions; writes nothing" },
+                { long: "--limit", value_name: "N", description: "Affected rows per page, 1..100 (default 20); counts always cover the complete corpus" },
+                { long: "--offset", value_name: "N", description: "Nonnegative affected-row offset" },
+            ],
+            async run(ctx) {
+                const { input, catalog, approve, limit, offset } = ctx.options;
+                if (typeof input !== "string" || catalog !== undefined && typeof catalog !== "string" || approve !== undefined && typeof approve !== "string") {
+                    throw createPmCliExpectedError("Supply --input <JSON file>, optional --catalog <JSON file> and a full --approve digest.", { exitCode: 2, context: { code: "invalid_input", required: "Use pm github labels plan --help and the documented JSON example." } });
+                }
+                return planGithubLabelMigration(ctx.pm_root, readLabelMigrationJson(input), {
+                    page: { limit: limit === undefined ? undefined : Number(limit), offset: offset === undefined ? undefined : Number(offset) },
+                    approval: approve,
+                    readCatalog: catalog === undefined ? undefined : async () => readLabelMigrationJson(catalog),
+                });
+            },
+        });
         api.registerCommand({
             name: "github refresh",
             description: "Refresh existing linked items from GitHub without importing new issues.",
@@ -5743,6 +5825,19 @@ export default defineExtension({
                 return report;
             },
         });
+        // Receipts stay private until the workflow scans the selected diagnostic.
+        api.registerCommand({
+            name: "github workflow-diagnostic",
+            description: "Select one actionable refusal from private workflow receipts. Privacy-scan before publishing the result.",
+            flags: [
+                { long: "--report", value_name: "file", description: "Command JSON stdout receipt" },
+                { long: "--error-file", value_name: "file", description: "Command stderr receipt" },
+                { long: "--diff", value_name: "file", description: "Repeat-import tracker diff" },
+            ],
+            async run(ctx) {
+                return readWorkflowFailure(optionString(ctx.options, "report"), optionString(ctx.options, "error-file", "errorFile"), optionString(ctx.options, "diff"));
+            },
+        });
         // Closeout uses the existing repository resolution and REST transport.
         api.registerCommand({
             name: "github closeout",
@@ -5765,8 +5860,12 @@ export default defineExtension({
                     const report = await runCloseout(ctx.pm_root, resolveSearchRepo(ctx.options), ctx.options, {
                         base: githubApiBase(), get: url => fetchJSON(url, token), next: parseNextLink,
                     });
-                    if (report.failed > 0)
+                    if (report.failed > 0) {
+                        // Preserve the full private receipt before the host formats or budgets its error message.
+                        if (ctx.global.json === true)
+                            process.stdout.write(`${JSON.stringify(report)}\n`);
                         throw new CommandError(JSON.stringify({ ...report, error: "pm github closeout: some closes failed" }), EXIT_CODE.GENERIC_FAILURE);
+                    }
                     return ctx.global.json === true || ctx.options.full === true ? report : compactCloseoutReport(report);
                 }
                 catch (error) {