pm-github 2026.9.26 → 2026.10.8

package/dist/index.js

@@ -2,6 +2,7 @@
 //
 // Capabilities (see manifest.json):
 //   commands   — `pm gh-issues import` (legacy) + `pm github sync` +
+//                `pm github gate` (fail-closed pre-push privacy gate) +
 //                `pm github project list|fields|import|sync` (Projects v2)
 //   importers  — `pm github import <owner/repo>` (idempotent native import)
 //   exporters  — `pm github export` (render pm items as a GitHub-issues payload)
@@ -20,7 +21,9 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { comments as pmCommentsFn, commitItemMutations as sdkCommitItemMutations, listAllItemMetadata as sdkListAllItemMetadata, normalizeItemId as sdkNormalizeItemId, readSettings as sdkReadSettings, } from "@unbrained/pm-cli/sdk";
 import { collectNewOrderingCycleWarnings as sdkCollectNewOrderingCycleWarnings } from "@unbrained/pm-cli/sdk/graph";
-import { buildProjectImportPlan, buildProjectPullPlan, buildProjectPushPlan, parseProjectItemTag, parseProjectRef, parseStatusMap, projectItemTag, } from "./projects.js";
+import { GateInputError, formatGateReport, runTrackerGate, resolvePmDataDir, } from "./gate.js";
+export { resolvePmDataDir } from "./gate.js";
+import { buildProjectImportPlan, buildProjectPullPlan, buildProjectPushPlan, parseProjectItemTag, parseProjectRef, parseStatusMap, parseAssignmentMap, projectItemTag, } from "./projects.js";
 const COMMENTS_MODES = ["body", "annotations", "both"];
 // Resolve a GitHub token so the importer is not stuck on the 60 req/hr
 // unauthenticated quota and can read private repos. Order: explicit env vars,
@@ -29,20 +32,19 @@ export function resolveGitHubToken() {
     const envToken = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
     if (envToken && envToken.trim())
         return envToken.trim();
-    try {
-        const result = spawnSync("gh", ["auth", "token"], { encoding: "utf-8" });
-        if (result.status === 0) {
-            const token = result.stdout.trim();
-            if (token)
-                return token;
-        }
-    }
-    catch {
-        // gh not installed — fall back to unauthenticated requests.
+    // spawnSync never throws for a missing executable: it reports ENOENT through
+    // `result.error`/`status: null` (verified against the Node subprocess
+    // contract), and the arguments here are fixed and valid, so there is no
+    // throwable failure left — the status check below is the whole boundary.
+    const result = spawnSync("gh", ["auth", "token"], { encoding: "utf-8", env: { ...process.env } });
+    if (result.status === 0) {
+        const token = result.stdout.trim();
+        if (token)
+            return token;
     }
     return undefined;
 }
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const sleep = (ms) => new Promise((r) => { setTimeout(r, ms); });
 /**
  * Decide whether the Authorization token may be forwarded across a redirect.
  *
@@ -117,6 +119,7 @@ export function githubApiBase() {
  * token only to same-origin targets via {@link sameOrigin}.
  */
 function requestOnce(method, url, token, payload, redirectsLeft = 5) {
+    let deadline;
     return new Promise((resolve, reject) => {
         const headers = {
             "User-Agent": "pm-github",
@@ -135,7 +138,7 @@ function requestOnce(method, url, token, payload, redirectsLeft = 5) {
         const target = new URL(url);
         const transport = target.protocol === "http:" ? http : https;
         const req = transport.request(target, { method, headers }, (res) => {
-            const status = res.statusCode ?? 0;
+            const status = res.statusCode; // Node guarantees an Integer statusCode on every ClientResponse.
             if (status >= 300 && status < 400 && res.headers.location) {
                 // Drain the redirect response so the socket is returned to the pool.
                 res.resume();
@@ -173,13 +176,19 @@ function requestOnce(method, url, token, payload, redirectsLeft = 5) {
             });
         });
         req.on("error", reject);
-        req.setTimeout(30000, () => {
-            req.destroy(new Error("request timed out after 30s"));
-        });
+        // A wall-clock deadline also bounds redirects and stalled response bodies.
+        // Bun's ClientRequest socket timeout can fail to fire on a silent server.
+        deadline = setTimeout(() => {
+            const error = new Error("request timed out after 30s");
+            // Reject before destroy: Bun can synchronously emit response end during
+            // destruction, which must never turn a truncated timed-out body into success.
+            reject(error);
+            req.destroy(error);
+        }, 30000);
         if (payload)
             req.write(payload);
         req.end();
-    });
+    }).finally(() => clearTimeout(deadline));
 }
 /**
  * Compute how long (ms) to wait before retrying a rate-limited or transient
@@ -269,7 +278,22 @@ export function formatRateLimit(info) {
 }
 // Decide whether a failed HTTP response is worth retrying: 429, any 5xx, or a
 // 403 that is actually a primary/secondary rate-limit wall (remaining=0).
-function isRetryableStatus(status, headers) {
+//
+/**
+ * Decide whether a failed HTTP response is worth retrying.
+ *
+ * Retries 429, any 5xx, and a 403 that is actually a primary/secondary
+ * rate-limit wall (remaining=0 or a Retry-After). Mixed-case header keys are
+ * honored defensively: Node's HTTP client lowercases response names, but the
+ * shared headers record also serves boundary tests that pass other shapes.
+ *
+ * @internal Exported only so the HTTP-boundary tests can drive the real
+ * decision. `stripInternal` keeps it out of the published `.d.ts`.
+ * @param status - The HTTP status code of the failed response.
+ * @param headers - The response headers to read the rate-limit hints from.
+ * @returns True when the request should be retried with backoff.
+ */
+export function isRetryableStatus(status, headers) {
     if (status === 429)
         return true;
     if (status >= 500)
@@ -355,7 +379,7 @@ export function optionString(options, ...keys) {
 }
 // Whether an option key was explicitly provided (even if empty/falsey).
 export function optionProvided(options, ...keys) {
-    return keys.some((k) => Object.prototype.hasOwnProperty.call(options, k));
+    return keys.some((k) => Object.hasOwn(options, k));
 }
 // Parse a `--since` value into an ISO timestamp the GitHub `since` query param
 // accepts. Accepts either an ISO 8601 timestamp (passed through, invalid date
@@ -394,20 +418,7 @@ export function parseSince(value, nowMs = Date.now()) {
 export function parseLabelMap(options, ...keys) {
     const lookup = keys.length > 0 ? keys : ["label-map", "labelMap"];
     const raw = optionCsv(options, ...lookup);
-    if (raw.length === 0)
-        return undefined;
-    const map = new Map();
-    for (const entry of raw) {
-        const eq = entry.indexOf("=");
-        if (eq <= 0)
-            continue; // need a non-empty "from" before the '='
-        const from = entry.slice(0, eq).trim();
-        const to = entry.slice(eq + 1).trim();
-        if (!from || !to)
-            continue;
-        map.set(from, to);
-    }
-    return map.size > 0 ? map : undefined;
+    return parseAssignmentMap(raw);
 }
 // Apply a label translation table to a list of labels. Labels with a mapping
 // are replaced; unmapped labels pass through unchanged. Two source labels that
@@ -761,7 +772,7 @@ export function readPmItems(pmRoot, platform = process.platform, pmPackageRoot =
         command = process.execPath;
         args = [cliEntry, ...listArgs];
     }
-    const result = spawnSync(command, args, { encoding: "utf-8", maxBuffer });
+    const result = spawnSync(command, args, { encoding: "utf-8", maxBuffer, env: { ...process.env } });
     // A buffer overrun kills the child with status null and no stderr, so name the
     // real cause instead of reporting an unexplained failure.
     if (result.error) {
@@ -846,6 +857,10 @@ export function indexByProvenance(items) {
     }
     return index;
 }
+/** Render thrown values consistently across subprocess, SDK, and HTTP boundaries. */
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 // ---------------------------------------------------------------------------
 // Atomic GitHub issue import (pm-cli >= 2026.7.20 commitItemMutations)
 // ---------------------------------------------------------------------------
@@ -889,11 +904,15 @@ export async function resolveCommitItemMutations(importSdk) {
     return cachedCommitItemMutations;
 }
 async function resolveAtomicSdkFunctions(opts) {
-    const needsSdk = !opts.commitItemMutations || !opts.normalizeItemId || !opts.readSettings;
     return {
-        commitItemMutations: opts.commitItemMutations ?? assertSdkFunction(needsSdk ? sdkCommitItemMutations : undefined, "commitItemMutations"),
-        normalizeItemId: opts.normalizeItemId ?? assertSdkFunction(needsSdk ? sdkNormalizeItemId : undefined, "normalizeItemId"),
-        readSettings: opts.readSettings ?? assertSdkFunction(needsSdk ? sdkReadSettings : undefined, "readSettings"),
+        // Each `??` fallback runs only when the injected option is absent, so the
+        // SDK function is always the value handed onward; a separate `needsSdk ?`
+        // branch inside the fallback can never select anything else (when every
+        // option is injected the fallbacks do not run at all), so the SDK binding
+        // is passed directly.
+        commitItemMutations: opts.commitItemMutations ?? assertSdkFunction(sdkCommitItemMutations, "commitItemMutations"),
+        normalizeItemId: opts.normalizeItemId ?? assertSdkFunction(sdkNormalizeItemId, "normalizeItemId"),
+        readSettings: opts.readSettings ?? assertSdkFunction(sdkReadSettings, "readSettings"),
     };
 }
 /**
@@ -1058,7 +1077,7 @@ export async function importGithubAtomic(pmRoot, repo, entries, opts = {}) {
         };
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = errorMessage(err);
         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);
         }
@@ -1132,10 +1151,10 @@ export async function fetchComments(issue, repo, token) {
             page = JSON.parse(body);
         }
         catch {
-            break;
+            throw new CommandError("GitHub comments response is not valid JSON.");
         }
         if (!Array.isArray(page))
-            break;
+            throw new CommandError("GitHub comments response must be an array.");
         comments.push(...page);
         nextUrl = parseNextLink(linkHeader);
     }
@@ -1204,28 +1223,6 @@ export function composeBody(issue, comments) {
 export const IMPORT_LOCK_TTL_MS_DEFAULT = 5 * 60_000;
 /** Default total budget a caller waits to acquire a contended comment-sync lock before giving up and skipping that item's sync. */
 export const IMPORT_LOCK_WAIT_MS_DEFAULT = 30_000;
-/**
- * Resolve the pm data dir from the `pmRoot` a command handler receives.
- *
- * The host may hand either the workspace root (the dir containing `.agents/pm`)
- * or the data dir itself — the pm CLI accepts both for `--path`. This returns
- * the dir that actually holds `settings.json` and `locks/`, defaulting to
- * `pmRoot` unchanged when no nested `.agents/pm` exists.
- *
- * @param pmRoot - The path supplied by the extension host.
- * @returns The resolved pm data directory.
- */
-export function resolvePmDataDir(pmRoot) {
-    const nested = path.join(pmRoot, ".agents", "pm");
-    try {
-        if (fs.statSync(nested).isDirectory())
-            return nested;
-    }
-    catch {
-        // Not the workspace-root form — assume pmRoot already is the data dir.
-    }
-    return pmRoot;
-}
 /**
  * Absolute lock file path for one item's comment-sync critical section.
  *
@@ -1274,13 +1271,17 @@ function readImportLockPayload(lockPath) {
  *
  * Signals the PID with signal 0 (no effect); `EPERM` means the process exists
  * but belongs to another user (still alive), while `ESRCH` means it is gone.
- * Non-numeric or non-positive PIDs are treated as not-alive.
+ * Non-positive PIDs are treated as not-alive. The sole production caller already
+ * rejects non-numeric PIDs before calling, so this function does not re-check the type.
  *
- * @param pid - The recorded owner PID (untyped at the call site).
+ * @internal Exported so the lock tests can drive the PID boundary directly.
+ * `stripInternal` keeps it out of the published declarations.
+ * @param pid - The recorded owner PID. Callers pass a positive integer; non-positive
+ * values are rejected here so a direct call cannot signal the process group.
  * @returns True when the PID names a live process.
  */
-function isLockOwnerAlive(pid) {
-    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
+export function isLockOwnerAlive(pid) {
+    if (pid <= 0)
         return false;
     try {
         process.kill(pid, 0);
@@ -1444,7 +1445,7 @@ export async function acquireImportLock(pmRoot, itemId, opts = {}) {
         fs.mkdirSync(path.dirname(lockPath), { recursive: true });
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = errorMessage(err);
         console.error(`pm-github: comment-sync lock unavailable (${msg}) — proceeding without cross-process serialization`);
         return { status: "degraded" };
     }
@@ -1513,11 +1514,13 @@ export async function acquireImportLock(pmRoot, itemId, opts = {}) {
             }
             const code = err?.code;
             if (code !== "EEXIST") {
-                const msg = err instanceof Error ? err.message : String(err);
+                const msg = errorMessage(err);
                 console.error(`pm-github: comment-sync lock failed (${msg}) — proceeding without cross-process serialization`);
                 return { status: "degraded" };
             }
-            // The lock exists. If it vanished before we could stat it, retry at once.
+            // The lock exists for open(O_EXCL) but cannot be stat'd (it vanished, or
+            // it is a broken symlink). Retry, but honor the wait budget: a persistent
+            // stat failure must not busy-spin the process until an external killer.
             let existing;
             let mtimeMs = Number.NaN;
             try {
@@ -1525,6 +1528,10 @@ export async function acquireImportLock(pmRoot, itemId, opts = {}) {
                 existing = readImportLockPayload(lockPath);
             }
             catch {
+                const vanishedForMs = Date.now() - startedAt;
+                if (vanishedForMs >= waitMs)
+                    return { status: "contended" };
+                await sleep(Math.min(backoffMs, Math.max(1, waitMs - vanishedForMs)));
                 continue;
             }
             const staleReason = importLockStaleReason(lockPath, existing, mtimeMs, ttlMs);
@@ -1661,24 +1668,26 @@ export function parseCreatedItemId(stdout) {
  *
  * Idempotent: comments already present (matched by their marker id) are skipped,
  * so re-running import never duplicates. Each GitHub comment becomes one pm
- * comment authored by the GitHub login. Failures are logged and never abort the
- * import; a contended or unavailable lock degrades gracefully (see
- * {@link acquireImportLock}).
+ * comment authored by the GitHub login. Failures are reported in the returned
+ * `failed` count and logged, never thrown: a contended or unavailable lock, an
+ * unreadable existing-comment collection, and each refused add all count every
+ * comment that did not land (see {@link acquireImportLock}). Gated callers turn
+ * a non-zero `failed` count into a fail-closed refusal; ungated ones continue.
  *
  * @param itemId - The pm item to append comments to.
  * @param comments - The GitHub comments to sync.
  * @param pmRoot - Workspace root or pm data dir.
  * @param issueNumber - The source issue number (for log prefixes).
- * @returns How many comments were added and how many skipped as duplicates.
+ * @returns How many comments were added, skipped as duplicates, and not written.
  */
 export async function syncGithubCommentsToAnnotations(itemId, comments, pmRoot, issueNumber) {
     if (comments.length === 0)
-        return { added: 0, skipped: 0 };
+        return { added: 0, skipped: 0, failed: 0 };
     const acquisition = await acquireImportLock(pmRoot, itemId);
     if (acquisition.status === "contended") {
         console.error(`#${issueNumber}: comment sync for ${itemId} skipped — another import holds the ` +
             `comment-sync lock; re-run import to pick up the comments`);
-        return { added: 0, skipped: 0 };
+        return { added: 0, skipped: 0, failed: comments.length };
     }
     const release = acquisition.status === "acquired" ? () => acquisition.lock.release() : () => { };
     try {
@@ -1688,13 +1697,14 @@ export async function syncGithubCommentsToAnnotations(itemId, comments, pmRoot,
             existing = list.comments;
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
+            const msg = errorMessage(err);
             console.error(`#${issueNumber}: could not read existing comments for ${itemId} — ${msg}`);
-            return { added: 0, skipped: 0 };
+            return { added: 0, skipped: 0, failed: comments.length };
         }
         const synced = extractSyncedCommentIds(existing);
         let added = 0;
         let skipped = 0;
+        let failed = 0;
         for (const c of comments) {
             if (synced.has(c.id)) {
                 skipped++;
@@ -1706,11 +1716,12 @@ export async function syncGithubCommentsToAnnotations(itemId, comments, pmRoot,
                 added++;
             }
             catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
+                const msg = errorMessage(err);
                 console.error(`#${issueNumber}: comment ${c.id} sync failed — ${msg}`);
+                failed++;
             }
         }
-        return { added, skipped };
+        return { added, skipped, failed };
     }
     finally {
         release();
@@ -1808,6 +1819,7 @@ export function parseImportOptions(options) {
         dryRun: optionEnabled(options, "dry-run", "dryRun"),
         atomic: optionEnabled(options, "atomic"),
         linkDeps: optionEnabled(options, "link-deps", "linkDeps"),
+        gate: optionEnabled(options, "gate"),
     };
 }
 // Spawn the `pm` CLI with the given argv and return a normalized ok/stdout/stderr
@@ -1815,7 +1827,7 @@ export function parseImportOptions(options) {
 // error-handling shape.
 function pmRun(args) {
     const maxBuffer = pmJsonMaxBuffer();
-    const result = spawnSync("pm", args, { encoding: "utf-8", maxBuffer });
+    const result = spawnSync("pm", args, { encoding: "utf-8", maxBuffer, env: { ...process.env } });
     return { ok: result.status === 0, stderr: result.stderr || "", stdout: result.stdout || "" };
 }
 // Strip fenced (```…```) and inline (`…`) code so `#123` mentions inside code
@@ -2037,7 +2049,7 @@ export async function linkImportedDependencies(repo, issues, pmRoot, deps = {})
             linked: 0,
             unresolved: 0,
             orderingCycleWarnings: [],
-            failures: [`dependency linking skipped: ${err instanceof Error ? err.message : String(err)}`],
+            failures: [`dependency linking skipped: ${errorMessage(err)}`],
         };
     }
     const provenance = buildProvenanceIndexFromMetadata(before);
@@ -2070,7 +2082,7 @@ export async function linkImportedDependencies(repo, issues, pmRoot, deps = {})
             }
         }
         catch (err) {
-            failures.push(`ordering-cycle advisory skipped: ${err instanceof Error ? err.message : String(err)}`);
+            failures.push(`ordering-cycle advisory skipped: ${errorMessage(err)}`);
         }
     }
     return { linked, unresolved, orderingCycleWarnings: [...warnings], failures };
@@ -2108,7 +2120,10 @@ async function prepareGithubImport(issue, repo, opts, token, match, fetchIssueCo
             comments = await fetchIssueComments(issue, repo, token);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
+            const msg = errorMessage(err);
+            if (opts.gate)
+                throw new CommandError(`pm github gate: comments for issue #${issue.number} could not be read.`);
+            // The gated case throws above, so this diagnostic always names the plain path.
             console.error(`#${issue.number}: failed to fetch comments — ${msg}`);
         }
     }
@@ -2132,14 +2147,172 @@ async function prepareGithubImport(issue, repo, opts, token, match, fetchIssueCo
         match,
     };
 }
+/**
+ * Verify that a gated import's plan accounts for every fetched issue exactly once.
+ *
+ * An import that silently drops an issue (or plans one twice) would leave the
+ * tracker out of sync with GitHub while reporting success, and the sync PR
+ * would then publish an incomplete state. The check is fail-closed: every
+ * filtered issue number must appear in the prepared entries or the explicit
+ * skip list exactly once, nothing outside the fetched set may appear, and the
+ * counts must reconcile. A violation throws {@link CommandError} before any
+ * mutation happens.
+ *
+ * @param issues - The filtered issues the fetch delivered.
+ * @param prepared - The plan entries built from them.
+ * @param skippedNumbers - Issue numbers the plan explicitly skips.
+ * @returns The reconciled counts on success.
+ */
+export function verifyImportPlanCompleteness(issues, prepared, skippedNumbers) {
+    const fetched = new Set(issues.map((issue) => issue.number));
+    const planned = new Set();
+    let duplicates = 0;
+    for (const entry of prepared) {
+        if (planned.has(entry.issueNumber))
+            duplicates++;
+        planned.add(entry.issueNumber);
+    }
+    const skippedSet = new Set(skippedNumbers);
+    const unaccounted = [...fetched].filter((number) => !planned.has(number) && !skippedSet.has(number));
+    const foreign = [...planned, ...skippedNumbers].filter((number) => !fetched.has(number));
+    const countsReconcile = prepared.length + skippedNumbers.length === issues.length;
+    const overlapping = skippedNumbers.some((number) => planned.has(number));
+    const duplicateFetch = fetched.size !== issues.length;
+    const duplicateSkip = skippedSet.size !== skippedNumbers.length;
+    if (overlapping || duplicateFetch || duplicateSkip || duplicates > 0 || unaccounted.length > 0 || foreign.length > 0 || !countsReconcile) {
+        throw new CommandError(`pm github gate: import plan is incomplete — fetched ${issues.length}, planned ${prepared.length}, ` +
+            `skipped ${skippedNumbers.length}; duplicates ${duplicates}, unaccounted [${unaccounted.join(", ")}], ` +
+            `out-of-plan [${foreign.join(", ")}]. No item was written.`, EXIT_CODE.GENERIC_FAILURE);
+    }
+    return { fetched: issues.length, planned: prepared.length, skipped: skippedNumbers.length };
+}
+/**
+ * Verify that a gated import's plan keeps a second run a no-op via provenance tags.
+ *
+ * Idempotency is only real when every re-import lands on exactly one item: a
+ * corpus with two items sharing a `gh:owner/repo#N` tag updates one and lets the
+ * other drift, and a plan entry targeting a second entry's item would write the
+ * same item twice. The check fails closed on duplicate provenance tags in the
+ * existing corpus, on plan entries that would create a new item without its
+ * provenance tag, and on two plan entries resolving to the same existing item.
+ *
+ * @param existing - The complete existing pm item corpus.
+ * @param prepared - The plan entries about to be written.
+ * @param repo - The `owner/repo` being imported from.
+ * @returns The provenance idempotency receipts on success.
+ */
+export function verifyImportIdempotency(existing, prepared, repo) {
+    const tagOwners = new Map();
+    const duplicateTags = new Set();
+    for (const item of existing) {
+        if (!item.id)
+            continue;
+        for (const tag of item.tags ?? []) {
+            const parsed = parseProvenanceTag(tag);
+            if (!parsed)
+                continue;
+            const key = `${parsed.repo}#${parsed.number}`;
+            const prior = tagOwners.get(key);
+            if (prior && prior !== item.id)
+                duplicateTags.add(key);
+            else
+                tagOwners.set(key, item.id);
+        }
+    }
+    const matchedIds = [];
+    let untaggedNewEntries = 0;
+    for (const entry of prepared) {
+        if (entry.match?.id) {
+            matchedIds.push(entry.match.id);
+            continue;
+        }
+        if (!entry.tags.includes(provenanceTag(repo, entry.issueNumber)))
+            untaggedNewEntries++;
+    }
+    const conflictingTargets = matchedIds.length - new Set(matchedIds).size;
+    if (duplicateTags.size > 0 || untaggedNewEntries > 0 || conflictingTargets > 0) {
+        throw new CommandError(`pm github gate: import plan is not idempotent — ${duplicateTags.size} duplicate provenance tag(s) ` +
+            `in the existing corpus, ${untaggedNewEntries} new entr(y/ies) without a provenance tag, ` +
+            `${conflictingTargets} conflicting target(s). No item was written.`, EXIT_CODE.GENERIC_FAILURE);
+    }
+    return {
+        provenance_indexed: tagOwners.size,
+        matched_by_provenance: matchedIds.length,
+        new_entries: prepared.length - matchedIds.length,
+    };
+}
+/**
+ * Verify the persisted corpus actually contains every issue in the written plan.
+ *
+ * A recovered SDK journal alone is insufficient evidence after local files are
+ * reset or removed. Require unique durable provenance before a caller may push.
+ *
+ * @param existing - Complete post-write item corpus.
+ * @param prepared - Every entry the verified plan required.
+ * @param repo - Source repository whose provenance must be present.
+ * @returns Number of durable issue identities verified.
+ */
+export function verifyImportedProvenance(existing, prepared, repo) {
+    const index = indexByProvenance(existing);
+    const persisted = prepared.map(entry => ({ ...entry, match: index.get(`${repo.toLowerCase()}#${entry.issueNumber}`) }));
+    if (persisted.some(entry => !entry.match?.id))
+        throw new CommandError("pm github gate: persisted corpus does not account for the complete import plan. Nothing may be pushed.");
+    verifyImportIdempotency(existing, persisted, repo);
+    return persisted.length;
+}
+/**
+ * Execute the real tracker gate with the shared fail-closed command error boundary.
+ *
+ * @internal Exported to verify collaborator failures against real Git fixtures.
+ * @param input - Tracker root and optional gate input dependencies.
+ * @returns A completed gate report; unexpected errors are redacted.
+ */
+export function runCommandTrackerGate(input) {
+    try {
+        return runTrackerGate(input);
+    }
+    catch (error) {
+        throw new CommandError(error instanceof GateInputError ? error.message : "pm github gate: scanner error; scan did not complete.", EXIT_CODE.GENERIC_FAILURE);
+    }
+}
+/**
+ * Run the post-write tracker privacy gate and turn its outcome into a receipt.
+ *
+ * Runs the real gate over the proposed tracker change the import just wrote,
+ * emits the human-readable report to stderr, and throws {@link CommandError}
+ * with the findings (rule + item + field + hash — never the matched content)
+ * when the verdict is fail, so a caller higher in the pipeline (a sync workflow)
+ * never reaches its commit/push step on a gated failure. Gate input failures
+ * (not a Git work tree, unreadable change, malformed allowlist) fail identically.
+ *
+ * @param pmRoot - Workspace root or pm data dir the import wrote to.
+ * @returns The pass receipt, embedded into the import result.
+ */
+function gateImportWrites(pmRoot) {
+    const report = runCommandTrackerGate({ pmRoot });
+    const lines = formatGateReport(report);
+    console.error(lines.join("\n"));
+    if (report.verdict === "fail") {
+        throw new CommandError(JSON.stringify({ ...report, error: "pm github gate: FAIL" }), EXIT_CODE.GENERIC_FAILURE);
+    }
+    return {
+        verdict: report.verdict,
+        scanned_files: report.scanned_files,
+        findings: report.findings.length,
+        allowlisted: report.allowlisted,
+    };
+}
 /**
  * Run the full GitHub issue import flow.
  *
  * Idempotent: items already linked (by provenance tag) to a fetched issue are
  * UPDATEd; new issues are created. Honors `--atomic` (one crash-resumable
  * transaction) versus the per-item `pm` mutation path, optional `--link-deps`,
- * and `--dry-run`. Returns a structured result and throws {@link CommandError}
- * (with a semantic exit code) on failure.
+ * and `--dry-run`. With `--gate` the plan is verified (completeness + provenance
+ * idempotency) BEFORE any mutation, and the proposed tracker change is scanned
+ * by the fail-closed privacy gate AFTER it — a gated failure exits non-zero so
+ * a caller never commits or pushes the change. Returns a structured result and
+ * 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.
@@ -2161,7 +2334,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         fetched = await (dependencies.fetchIssues ?? fetchAllIssues)(repo, opts, token);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = errorMessage(err);
         const hint = !token && /HTTP 403/.test(msg)
             ? " — set GITHUB_TOKEN/GH_TOKEN or run `gh auth login` to raise the rate limit (60→5000/hr) and reach private repos"
             : "";
@@ -2171,6 +2344,9 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
     const filtered = applyClientFilters(fetched, opts);
     if (filtered.length === 0) {
         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;
         if (opts.atomic && opts.dryRun) {
             return {
                 dryRun: true,
@@ -2180,7 +2356,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                 atomic: true,
             };
         }
-        return { imported: 0, updated: 0, skipped: 0 };
+        return { imported: 0, updated: 0, skipped: 0, ...(emptyGateReceipt ? { gate: emptyGateReceipt } : {}) };
     }
     console.error(`Found ${filtered.length} issue(s).`);
     // Build the idempotency index once up-front — including for a dry run. Skipping
@@ -2188,20 +2364,64 @@ 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 existing = indexByProvenance((dependencies.readItems ?? readPmItems)(pmRoot));
+    const existingItems = (dependencies.readItems ?? readPmItems)(pmRoot);
+    const existing = indexByProvenance(existingItems);
     let imported = 0;
     let updated = 0;
     let skipped = 0;
-    if (opts.atomic) {
-        const prepared = [];
+    // 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
+    // (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.
+    let gatePlan;
+    let gateCompleteness;
+    let gateIdempotency;
+    let gatePlanByNumber;
+    if (opts.gate || opts.atomic) {
+        const planned = [];
+        const skippedNumbers = [];
         for (const issue of filtered) {
             const entry = await prepareGithubImport(issue, repo, opts, token, existing.get(`${repo.toLowerCase()}#${issue.number}`), dependencies.fetchIssueComments);
             if (!entry) {
-                skipped++;
+                skippedNumbers.push(issue.number);
                 continue;
             }
-            prepared.push(entry);
+            planned.push(entry);
+        }
+        if (opts.gate) {
+            gateCompleteness = verifyImportPlanCompleteness(filtered, planned, skippedNumbers);
+            gateIdempotency = verifyImportIdempotency(existingItems, planned, repo);
         }
+        gatePlan = planned;
+        gatePlanByNumber = new Map(planned.map((entry) => [entry.issueNumber, entry]));
+        skipped = skippedNumbers.length;
+        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,
+                        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,
+                        })) : [] },
+                })) });
+            if (preview.verdict === "fail")
+                throw new CommandError(JSON.stringify({ ...preview, error: "pm github gate: FAIL before write" }));
+        }
+        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" } } : {};
+    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
+        // phase cannot diverge from the verified plan.
+        const prepared = [...gatePlan];
         if (prepared.length === 0) {
             if (opts.dryRun) {
                 console.error(`[dry-run] Atomic plan would import 0, update 0, skip ${skipped}.`);
@@ -2220,7 +2440,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             updated = prepared.length - imported;
             for (const entry of prepared) {
                 const action = entry.match?.id ? "update" : "import";
-                console.error(`  [dry-run][atomic] #${entry.issueNumber} ${action}: ${entry.title} (${entry.status})`);
+                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}.`);
             if (opts.linkDeps) {
@@ -2234,17 +2454,29 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                 wouldSkip: skipped,
                 atomic: true,
                 ...(opts.linkDeps ? { wouldLinkDependencyCandidates: countDependencyRefCandidates(repo, filtered) } : {}),
+                ...gatePlanFields,
             };
         }
         const result = await (dependencies.commitAtomic ?? importGithubAtomic)(pmRoot, repo, prepared);
+        if (opts.gate)
+            verifyImportedProvenance((dependencies.readItems ?? readPmItems)(pmRoot), 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
+        // counted and gated runs fail closed below instead of exiting clean.
+        let commentWriteFailures = 0;
         for (const entry of prepared) {
             if (!entry.syncAnnotations)
                 continue;
             const itemId = result.itemIds.get(entry.issueNumber);
             if (itemId) {
-                await syncGithubCommentsToAnnotations(itemId, entry.comments, pmRoot, entry.issueNumber);
+                commentWriteFailures += (await syncGithubCommentsToAnnotations(itemId, entry.comments, pmRoot, entry.issueNumber)).failed;
+            }
+            else {
+                commentWriteFailures += entry.comments.length;
             }
         }
+        failClosedOnPlanDivergence(opts.gate, skipped, skipped, commentWriteFailures);
         if (result.recovered) {
             console.error(`Atomic import recovered transaction ${result.transactionId} covering ${result.recoveredItems ?? prepared.length} item(s).`);
         }
@@ -2257,6 +2489,9 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         reportDepLink(atomicDepLink);
         // itemIds is an internal post-commit routing map for native comments. Maps
         // serialize as `{}` in JSON, so keep it out of the public command result.
+        // Gated pipeline, phase 2 — the writes are on disk but nothing is committed
+        // or pushed; scan the proposed tracker change now and fail closed.
+        const gateReceipt = opts.gate ? gateImportWrites(pmRoot) : undefined;
         return {
             transactionId: result.transactionId,
             recovered: result.recovered,
@@ -2266,12 +2501,21 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             skipped,
             atomic: true,
             ...depLinkResultFields(atomicDepLink),
+            ...(gateReceipt ? { gate: gateReceipt } : {}),
         };
     }
     for (const issue of filtered) {
-        const prepared = await prepareGithubImport(issue, repo, opts, token, existing.get(`${repo.toLowerCase()}#${issue.number}`), dependencies.fetchIssueComments);
+        // 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);
         if (!prepared) {
-            skipped++;
+            // 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);
@@ -2295,8 +2539,8 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         };
         if (opts.dryRun) {
             const action = match?.id ? "update" : "import";
-            const metadata = labels.length > 0 ? `${status}, ${labels.join(",")}` : status;
-            console.error(`  [dry-run] #${issue.number} ${action}: ${title} (${metadata})`);
+            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)
                 updated++;
             else
@@ -2344,7 +2588,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                 }
             }
             if (syncAnnotations) {
-                await syncGithubCommentsToAnnotations(match.id, comments, pmRoot, issue.number);
+                commentWriteFailures += (await syncGithubCommentsToAnnotations(match.id, comments, pmRoot, issue.number)).failed;
             }
             updated++;
             continue;
@@ -2401,10 +2645,14 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         }
         if (syncAnnotations) {
             if (createdId) {
-                await syncGithubCommentsToAnnotations(createdId, comments, pmRoot, issue.number);
+                commentWriteFailures += (await syncGithubCommentsToAnnotations(createdId, comments, pmRoot, issue.number)).failed;
             }
             else {
+                // Without the created id the planned comments cannot be written; the
+                // gated plan-divergence refusal below turns that into a fail-closed exit
+                // while ungated runs keep today's warn-and-continue behaviour.
                 console.error(`#${issue.number}: could not parse created item id — comments not synced`);
+                commentWriteFailures += comments.length;
             }
         }
         imported++;
@@ -2420,19 +2668,30 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             wouldImport: imported,
             wouldUpdate: updated,
             wouldSkip: skipped,
-            ...(opts.atomic ? { atomic: true } : {}),
             ...(opts.linkDeps ? { wouldLinkDependencyCandidates: countDependencyRefCandidates(repo, filtered) } : {}),
+            ...gatePlanFields,
         };
     }
     console.error(`Imported ${imported} new, updated ${updated} existing, skipped ${skipped}.`);
     if (imported === 0 && updated === 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
+    // (an update, close or reopen reconciliation) or a planned native comment
+    // that was not written leaves the tracker different from the verified plan,
+    // and provenance alone cannot see that, because the item still carries its
+    // tag. Fail closed before anything can be pushed.
+    failClosedOnPlanDivergence(opts.gate, gateCompleteness?.skipped ?? skipped, skipped, commentWriteFailures);
     const depLink = opts.linkDeps
         ? await linkImportedDependencies(repo, filtered, pmRoot, dependencies)
         : undefined;
     reportDepLink(depLink);
-    return { imported, updated, skipped, ...depLinkResultFields(depLink) };
+    // 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);
+    const gateReceipt = opts.gate ? gateImportWrites(pmRoot) : undefined;
+    return { imported, updated, skipped, ...depLinkResultFields(depLink), ...(gateReceipt ? { gate: gateReceipt } : {}) };
 }
 /**
  * Emit the human-readable `--link-deps` summary to stderr.
@@ -2469,12 +2728,50 @@ function depLinkResultFields(result) {
         ...(result.failures.length > 0 ? { dependencyLinkFailures: result.failures } : {}),
     };
 }
+/**
+ * Fail a gated import when the writes diverged from the verified plan.
+ *
+ * A gated import is all-or-nothing in effect: a planned item write that failed
+ * (an update, close or reopen reconciliation), a planned native comment that
+ * was not written, or a comment collection left unreachable by an unparsable
+ * created id all leave the tracker different from the verified plan — and
+ * provenance alone cannot see that, because the item still carries its tag and
+ * missing content cannot leak anything into the post-write privacy scan. Both
+ * the non-atomic and the atomic import path funnel their divergence here and
+ * fail closed before anything can be pushed; ungated imports already warned.
+ *
+ * @param gate - Whether the import runs gated; ungated runs never throw here.
+ * @param plannedSkipped - Issues the verified plan already accounted as skipped.
+ * @param actualSkipped - Issues the write phase actually skipped.
+ * @param commentFailures - Planned native comments that were not written.
+ * @throws CommandError when any planned write or comment failed on a gated run.
+ */
+function failClosedOnPlanDivergence(gate, plannedSkipped, actualSkipped, commentFailures) {
+    const failed = actualSkipped - plannedSkipped + commentFailures;
+    if (!gate || failed <= 0)
+        return;
+    throw new CommandError(`pm github gate: ${failed} planned write(s) failed; the tracker does not match the verified plan. Nothing may be pushed.`);
+}
 // ---------------------------------------------------------------------------
 // Sync core — push pm status changes back to GitHub (close / reopen)
 // ---------------------------------------------------------------------------
 function pmStatusToGithubState(status) {
     return status === "closed" || status === "canceled" ? "closed" : "open";
 }
+/**
+ * Require every requested item before a remote sync or export can begin.
+ *
+ * @param items - Complete local corpus.
+ * @param requested - Selected ids, or an empty list for the complete corpus.
+ * @returns Matched items in corpus order.
+ * @throws CommandError when any requested identity is absent.
+ */
+function requireRequestedItems(items, requested) {
+    const scoped = scopeItemsByIds(items, requested.length > 0 ? requested : undefined);
+    if (scoped.missing.length > 0)
+        throw new CommandError(`--ids included unknown pm item id(s): ${scoped.missing.join(", ")}`, EXIT_CODE.NOT_FOUND);
+    return scoped.selected;
+}
 // 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) {
@@ -2504,8 +2801,8 @@ export function planSync(items, repo) {
 // Command handler for `pm github sync`: preview or apply the pm → GitHub issue
 // sync plan, scoped by --ids and honoring --dry-run / --apply.
 async function runSync(ctx) {
-    const options = ctx.options || {};
-    const repo = optionString(options, "repo") || ctx.args?.[0];
+    const options = ctx.options;
+    const repo = optionString(options, "repo") || ctx.args[0];
     const dryRun = optionEnabled(options, "dry-run", "dryRun");
     const idsProvided = optionProvided(options, "ids");
     const scopedIds = optionCsv(options, "ids");
@@ -2521,12 +2818,8 @@ async function runSync(ctx) {
         throw new CommandError("pm github sync needs a GitHub token to mutate issues " +
             "(set GITHUB_TOKEN/GH_TOKEN or run `gh auth login`). Use --dry-run to preview without a token.", EXIT_CODE.USAGE);
     }
-    const allItems = readPmItems(ctx.pm_root);
-    const scoped = scopeItemsByIds(allItems, scopedIds.length > 0 ? scopedIds : undefined);
-    if (scoped.missing.length > 0) {
-        throw new CommandError(`--ids included unknown pm item id(s): ${scoped.missing.join(", ")}`, EXIT_CODE.NOT_FOUND);
-    }
-    const plan = planSync(scoped.selected, repo);
+    const selected = requireRequestedItems(readPmItems(ctx.pm_root), scopedIds);
+    const plan = planSync(selected, repo);
     if (plan.length === 0) {
         const scopeNote = scopedIds.length > 0 ? ` from --ids (${scopedIds.join(", ")})` : "";
         console.error(`No pm items${scopeNote} linked to ${repo} ` +
@@ -2548,7 +2841,7 @@ async function runSync(ctx) {
             current = JSON.parse(body);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
+            const msg = errorMessage(err);
             console.error(`#${entry.number}: could not read upstream state — ${msg}`);
             skipped++;
             continue;
@@ -2568,7 +2861,7 @@ async function runSync(ctx) {
             synced++;
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
+            const msg = errorMessage(err);
             console.error(`#${entry.number}: PATCH failed — ${msg}`);
             skipped++;
         }
@@ -2675,7 +2968,7 @@ export async function applyExportPlan(plan, repo, token, requestFn) {
         catch (err) {
             // Isolate the failure: record it and keep going so one bad item never
             // abandons the items that follow it (and that may already be writable).
-            const msg = err instanceof Error ? err.message : String(err);
+            const msg = errorMessage(err);
             const label = entry.action === "update" && entry.number !== undefined
                 ? `#${entry.number}`
                 : entry.id ?? `"${p.title}"`;
@@ -2746,10 +3039,10 @@ export function applyOutcomeError(plan, result, repo) {
  * duplicated; `--label-map` translates pm tags to GitHub labels.
  */
 async function runExport(ctx) {
-    const options = ctx.options || {};
-    const jsonMode = ctx.global?.json === true;
+    const options = ctx.options;
+    const jsonMode = ctx.global.json === true;
     const format = optionString(options, "format") || "json";
-    const repo = optionString(options, "repo") || ctx.args?.[0];
+    const repo = optionString(options, "repo") || ctx.args[0];
     const apply = exportWillApply(options);
     const idsProvided = optionProvided(options, "ids");
     const scopedIds = optionCsv(options, "ids");
@@ -2757,12 +3050,8 @@ async function runExport(ctx) {
     if (idsProvided && scopedIds.length === 0) {
         throw new CommandError("--ids requires at least one pm item id (comma-separated), e.g. --ids pm-123,pm-456.", EXIT_CODE.USAGE);
     }
-    const allItems = readPmItems(ctx.pm_root);
-    const scoped = scopeItemsByIds(allItems, scopedIds.length > 0 ? scopedIds : undefined);
-    if (scoped.missing.length > 0) {
-        throw new CommandError(`--ids included unknown pm item id(s): ${scoped.missing.join(", ")}`, EXIT_CODE.NOT_FOUND);
-    }
-    const plan = buildExportPlan(scoped.selected, repo, labelMap);
+    const selected = requireRequestedItems(readPmItems(ctx.pm_root), scopedIds);
+    const plan = buildExportPlan(selected, repo, labelMap);
     const creates = plan.filter((e) => e.action === "create").length;
     const updates = plan.filter((e) => e.action === "update").length;
     if (!apply) {
@@ -2787,7 +3076,7 @@ async function runExport(ctx) {
                 console.error(JSON.stringify(plan, null, 2));
             }
             const scopeNote = scopedIds.length > 0
-                ? ` Scoped to ${scoped.selected.length} item(s) via --ids.`
+                ? ` Scoped to ${selected.length} item(s) via --ids.`
                 : "";
             const labelNote = labelMap && labelMap.size > 0
                 ? ` Label map applied (${labelMap.size} mapping(s)).`
@@ -2898,7 +3187,7 @@ export function mapSearchHits(matchedNumbers, repo, itemsByProvenance) {
         // (0, 1] so hits clear pm's default score threshold.
         hits.push({
             id: item.id,
-            score: matchedNumbers.length > 0 ? rank / matchedNumbers.length : 1,
+            score: rank / matchedNumbers.length,
             matched_fields: [`github:${repoLc}#${number}`],
         });
         rank--;
@@ -2925,13 +3214,8 @@ export function resolveSearchRepo(options) {
 }
 // Detect whether the `gh` CLI is installed and runnable on PATH.
 function detectGhCli() {
-    try {
-        const r = spawnSync("gh", ["--version"], { encoding: "utf-8" });
-        return r.status === 0;
-    }
-    catch {
-        return false;
-    }
+    const r = spawnSync("gh", ["--version"], { encoding: "utf-8", env: { ...process.env } });
+    return r.status === 0;
 }
 // Report which token source is active: `env` (GITHUB_TOKEN/GH_TOKEN), `gh` (gh
 // auth), or `none`.
@@ -2944,8 +3228,8 @@ function detectTokenSource() {
 // Command handler for `pm github validate`: checks token source, gh CLI, rate
 // limit, and the reachable issue counts for the configured repo.
 async function runValidate(ctx) {
-    const options = ctx.options || {};
-    const repo = optionString(options, "repo") || ctx.args?.[0];
+    const options = ctx.options;
+    const repo = optionString(options, "repo") || ctx.args[0];
     const gh_cli = detectGhCli();
     const token_source = detectTokenSource();
     const token = resolveGitHubToken();
@@ -2974,7 +3258,7 @@ async function runValidate(ctx) {
             report.repo = repo;
             try {
                 const res = await fetchJSON(`${githubApiBase()}/repos/${repo}`, token);
-                report.repo_accessible = res.status >= 200 && res.status < 300;
+                report.repo_accessible = true;
                 report.repo_status = res.status;
                 const rate = parseRateLimit(res.headers);
                 if (rate.remaining !== undefined)
@@ -2992,18 +3276,14 @@ async function runValidate(ctx) {
                         (token ? "" : " — set GITHUB_TOKEN/GH_TOKEN or run `gh auth login` to raise it (60→5000/hr)") +
                         ".");
                 }
-                if (report.repo_accessible) {
-                    report.messages.push(`Repo ${repo} is accessible (HTTP ${res.status}).`);
-                }
-                else {
-                    report.ok = false;
-                    report.messages.push(`Repo ${repo} returned HTTP ${res.status}.`);
-                }
+                // fetchJSON only resolves for 2xx; every other status throws into the catch
+                // below, so a returned response is accessible by construction.
+                report.messages.push(`Repo ${repo} is accessible (HTTP ${res.status}).`);
             }
             catch (err) {
                 report.ok = false;
                 report.repo_accessible = false;
-                report.messages.push(`Repo ${repo} check failed: ${err instanceof Error ? err.message : String(err)}`);
+                report.messages.push(`Repo ${repo} check failed: ${errorMessage(err)}`);
             }
         }
     }
@@ -3199,7 +3479,7 @@ async function fetchProjectItems(projectId, token) {
  */
 async function gqlAddDraft(projectId, title, body, token) {
     const q = `mutation($p:ID!,$t:String!,$b:String){ addProjectV2DraftIssue(input:{projectId:$p,title:$t,body:$b}){ projectItem{ id } } }`;
-    const d = await githubGraphQL(token, q, { p: projectId, t: title, b: body ?? "" });
+    const d = await githubGraphQL(token, q, { p: projectId, t: title, b: body });
     const id = d.addProjectV2DraftIssue?.projectItem?.id;
     if (!id)
         throw new CommandError("addProjectV2DraftIssue returned no item id.");
@@ -3335,8 +3615,8 @@ export async function listOwnerProjectsV2Nodes(owner, graphQL) {
  * @param ctx - The command-handler context.
  */
 async function runProjectList(ctx) {
-    const options = ctx.options || {};
-    const owner = optionString(options, "owner") || ctx.args?.[0];
+    const options = ctx.options;
+    const owner = optionString(options, "owner") || ctx.args[0];
     if (!owner) {
         throw new CommandError("Usage: pm github project list <owner>  (a GitHub user or org login)", EXIT_CODE.USAGE);
     }
@@ -3349,7 +3629,7 @@ async function runProjectList(ctx) {
         closed: !!n.closed,
         description: n.shortDescription ?? undefined,
     }));
-    if (ctx.global?.json !== true) {
+    if (ctx.global.json !== true) {
         if (projects.length === 0) {
             console.error(`No Projects v2 found for ${owner} (or none accessible with the resolved token).`);
         }
@@ -3362,6 +3642,22 @@ async function runProjectList(ctx) {
     }
     return { owner, projects };
 }
+/**
+ * Require a valid owner/number board reference before a project command can run.
+ *
+ * Resolves positional and --project forms identically for fields, import, and
+ * sync; a malformed reference exits before any GraphQL request or mutation.
+ *
+ * @param ctx - The host command context.
+ * @param usage - Command-specific recovery instruction.
+ * @returns The parsed project identity.
+ */
+function requireProjectRef(ctx, usage) {
+    const ref = parseProjectRef(optionString(ctx.options, "project") || ctx.args[0]);
+    if (!ref)
+        throw new CommandError(usage, EXIT_CODE.USAGE);
+    return ref;
+}
 // --- project fields --------------------------------------------------------
 /**
  * Command handler for `pm github project fields`: show a board's fields.
@@ -3372,11 +3668,8 @@ async function runProjectList(ctx) {
  * @param ctx - The command-handler context.
  */
 async function runProjectFields(ctx) {
-    const options = ctx.options || {};
-    const ref = parseProjectRef(optionString(options, "project") || ctx.args?.[0]);
-    if (!ref) {
-        throw new CommandError("Usage: pm github project fields <owner/number>  (e.g. pm github project fields unbraind/5)", EXIT_CODE.USAGE);
-    }
+    const options = ctx.options;
+    const ref = requireProjectRef(ctx, "Usage: pm github project fields <owner/number>  (e.g. pm github project fields unbraind/5)");
     const token = resolveGitHubToken();
     const meta = await resolveProject(ref, token);
     const q = `
@@ -3393,7 +3686,7 @@ async function runProjectFields(ctx) {
         type: f.dataType ?? f.__typename,
         options: Array.isArray(f.options) ? f.options.map((o) => o.name) : undefined,
     }));
-    if (ctx.global?.json !== true) {
+    if (ctx.global.json !== true) {
         console.error(`Project ${ref.owner}/${ref.number} — ${meta.title} (${meta.ownerType})`);
         console.error(`  ${meta.url}`);
         console.error(`  Status field: ${meta.statusField ? meta.statusField.options.map((o) => o.name).join(" | ") : "(none — pushes cannot set status)"}`);
@@ -3415,11 +3708,8 @@ async function runProjectFields(ctx) {
  * @param ctx - The command-handler context.
  */
 async function runProjectImport(ctx) {
-    const options = ctx.options || {};
-    const ref = parseProjectRef(optionString(options, "project") || ctx.args?.[0]);
-    if (!ref) {
-        throw new CommandError("Usage: pm github project import <owner/number> [--dry-run] [--status-map pm=Option,...] [--type <type>]", EXIT_CODE.USAGE);
-    }
+    const options = ctx.options;
+    const ref = requireProjectRef(ctx, "Usage: pm github project import <owner/number> [--dry-run] [--status-map pm=Option,...] [--type <type>]");
     const dryRun = optionEnabled(options, "dry-run", "dryRun");
     const itemType = optionString(options, "type") || "Task";
     const statusMap = parseStatusMap(optionCsv(options, "status-map", "statusMap"));
@@ -3554,19 +3844,16 @@ async function applyPushEntry(entry, meta, ref, pmById, pmRoot, token) {
         let itemId = entry.itemId;
         if (entry.action === "add-draft") {
             const pm = pmById.get(entry.pmId);
-            itemId = await gqlAddDraft(meta.id, entry.title, pm?.body || pm?.description, token);
+            itemId = await gqlAddDraft(meta.id, entry.title, pm.body || pm.description, token);
         }
         else if (entry.action === "add-issue") {
-            if (!entry.issueRepo || typeof entry.issueNumber !== "number") {
-                return { changed: false, error: "add-issue entry missing issue coordinates" };
-            }
+            // The private executor receives only buildProjectPushPlan entries. Its
+            // add-issue arm always sets both coordinates from a parsed provenance tag.
             const contentId = await gqlResolveIssueNodeId(entry.issueRepo, entry.issueNumber, token);
             if (!contentId)
                 return { changed: false, error: `could not resolve node id for ${entry.issueRepo}#${entry.issueNumber}` };
             itemId = await gqlAddIssue(meta.id, contentId, token);
         }
-        if (!itemId)
-            return { changed: false, error: "no project item id to act on" };
         if (entry.targetOptionId && meta.statusField) {
             await gqlSetStatus(meta.id, itemId, meta.statusField.id, entry.targetOptionId, token);
         }
@@ -3575,7 +3862,7 @@ async function applyPushEntry(entry, meta, ref, pmById, pmRoot, token) {
         const pm = pmById.get(entry.pmId);
         if (pm?.id) {
             const tag = projectItemTag(ref, itemId);
-            const existingTags = pm.tags ?? [];
+            const existingTags = pm.tags;
             if (!existingTags.includes(tag)) {
                 const upd = pmRun([
                     "--path", pmRoot, "update", pm.id,
@@ -3589,7 +3876,7 @@ async function applyPushEntry(entry, meta, ref, pmById, pmRoot, token) {
         return { changed: true };
     }
     catch (err) {
-        return { changed: false, error: err instanceof Error ? err.message : String(err) };
+        return { changed: false, error: errorMessage(err) };
     }
 }
 // Build the pm CLI argv that applies one pull (project → pm) status transition.
@@ -3659,11 +3946,8 @@ function applyPullEntry(entry, pmRoot) {
  * @param ctx - The command-handler context.
  */
 async function runProjectSync(ctx) {
-    const options = ctx.options || {};
-    const ref = parseProjectRef(optionString(options, "project") || ctx.args?.[0]);
-    if (!ref) {
-        throw new CommandError("Usage: pm github project sync <owner/number> [--push|--pull] [--apply] [--ids pm-1,..] [--status-map pm=Option,..] [--no-add-missing] [--prefer pm|github]", EXIT_CODE.USAGE);
-    }
+    const options = ctx.options;
+    const ref = requireProjectRef(ctx, "Usage: pm github project sync <owner/number> [--push|--pull] [--apply] [--ids pm-1,..] [--status-map pm=Option,..] [--no-add-missing] [--prefer pm|github]");
     const wantPush = optionEnabled(options, "push");
     const wantPull = optionEnabled(options, "pull");
     const dryRunFlag = optionEnabled(options, "dry-run", "dryRun");
@@ -3732,7 +4016,7 @@ async function runProjectSync(ctx) {
             for (const e of pullActionable)
                 console.error(`  ${e.pmId} "${e.title}": ${e.fromStatus} → ${e.toStatus}`);
             for (const s of pullPlan.statusSkipped) {
-                console.error(`  [skip] item ${s.itemId}: board status "${s.optionName ?? "(none)"}" maps to no pm status`);
+                console.error(`  [skip] item ${s.itemId}: board status "${s.optionName}" maps to no pm status`);
             }
             if (pullActionable.length === 0)
                 console.error("  (nothing to pull)");
@@ -3749,7 +4033,7 @@ async function runProjectSync(ctx) {
     let pushFailed = 0;
     if (applyPush && pushPlan) {
         for (const e of pushActionable) {
-            if (prefer === "github" && e.action === "set-status" && pullItemIds.has(e.itemId ?? "")) {
+            if (prefer === "github" && e.action === "set-status" && pullItemIds.has(e.itemId)) {
                 continue; // pull wins for this linked item
             }
             const r = await applyPushEntry(e, meta, ref, pmById, ctx.pm_root, token);
@@ -3832,6 +4116,7 @@ const IMPORT_FLAGS = [
     { long: "--comments-mode", value_name: "body|annotations|both", description: "How to persist fetched GitHub comments: `body` (default, embed in item body), `annotations` (sync to the pm item's native comments collection), or `both`. `annotations`/`both` are idempotent on re-import (dedupe by GitHub comment id)" },
     { long: "--atomic", description: "Commit the complete import as one workspace-writer-locked, crash-resumable transaction (pm-cli >=2026.7.20); compensate applied mutations on failure and report incomplete compensation" },
     { long: "--link-deps", description: "After import, map dependency references in issue bodies (`Blocked by #N`, `Depends on owner/repo#N`, `Blocks #N`) to pm dependency edges between the linked items. Idempotent; skips self- and unresolved references; ordering cycles are reported (via the SDK ordering-cycle advisory), not rejected" },
+    { long: "--gate", description: "Fail-closed privacy gate: verify plan completeness and provenance-tag idempotency before the write, then scan the proposed tracker change for credentials, personal data, and host paths after it; any finding (or unreadable scan input) fails the import so nothing is ever pushed" },
     { long: "--dry-run", description: "Preview without writing" },
     { long: "--type", value_name: "type", description: "Override pm item type (default: Issue)" },
 ];
@@ -3850,6 +4135,10 @@ const SYNC_FLAGS = [
     { long: "--ids", value_name: "pm-1,pm-2", description: "Only sync these pm item IDs (comma-separated)" },
     { long: "--dry-run", description: "Preview the close/reopen plan without mutating GitHub" },
 ];
+const GATE_FLAGS = [
+    { long: "--diff", value_name: "file", description: "Scan an explicit unified diff file instead of the staged/working tracker change (fail closed when unreadable)" },
+    { long: "--allowlist", value_name: "file", description: "Explicit content-hash allowlist of reviewed false positives (default: `<repo root>/.pm-github-gate-allowlist.json`; a missing EXPLICIT file fails, a missing default is an empty allowlist)" },
+];
 const VALIDATE_FLAGS = [
     { long: "--repo", value_name: "owner/repo", description: "Also check this repo is accessible with the resolved token" },
 ];
@@ -3887,7 +4176,7 @@ const PROJECT_SYNC_FLAGS = [
 const defineExtension = (module) => module;
 export default defineExtension({
     name: "pm-github",
-    version: "2026.9.26",
+    version: "2026.10.8",
     activate(api) {
         // -----------------------------------------------------------------------
         // schema — declare the GitHub provenance fields so the workspace knows them
@@ -3923,7 +4212,7 @@ export default defineExtension({
                 "github project sync",
             ],
             run: (ctx) => {
-                if (isMutatingGithubCommand(ctx.command, ctx.options || {})) {
+                if (isMutatingGithubCommand(ctx.command, ctx.options)) {
                     if (!resolveGitHubToken()) {
                         console.error("[pm-github preflight] this github command mutates remote state but no GitHub " +
                             "token is resolvable (GITHUB_TOKEN/GH_TOKEN or `gh auth login`). It will fail.");
@@ -3936,7 +4225,7 @@ export default defineExtension({
         // importer — `pm github import <owner/repo>` (idempotent native pipeline)
         // -----------------------------------------------------------------------
         api.registerImporter("github", async (ctx) => {
-            return runImport(ctx.args?.[0], ctx.pm_root, parseImportOptions(ctx.options || {}));
+            return runImport(ctx.args[0], ctx.pm_root, parseImportOptions(ctx.options));
         }, {
             description: "Fetch GitHub issues from a repo and create/update pm items (idempotent " +
                 "on re-import via the `gh:owner/repo#N` provenance tag). Skips pull " +
@@ -4003,7 +4292,7 @@ export default defineExtension({
             api.registerSearchProvider({
                 name: "github",
                 async query(qctx) {
-                    const repo = resolveSearchRepo(qctx.options || {});
+                    const repo = resolveSearchRepo(qctx.options);
                     if (!repo)
                         return [];
                     const token = resolveGitHubToken();
@@ -4042,10 +4331,10 @@ export default defineExtension({
             if (ctx.command !== "close" && ctx.command !== "update")
                 return;
             // Only nudge for items that are actually linked to GitHub.
-            const id = ctx.args?.[0];
+            const id = ctx.args[0];
             if (!id || !ctx.pm_root)
                 return;
-            const res = spawnSync("pm", ["--path", ctx.pm_root, "--json", "show", id], { encoding: "utf-8", maxBuffer: pmJsonMaxBuffer() });
+            const res = spawnSync("pm", ["--path", ctx.pm_root, "--json", "show", id], { encoding: "utf-8", maxBuffer: pmJsonMaxBuffer(), env: { ...process.env } });
             if (res.status !== 0)
                 return;
             let repo;
@@ -4131,6 +4420,48 @@ export default defineExtension({
             },
         });
         // -----------------------------------------------------------------------
+        // command — `pm github gate` (fail-closed privacy gate over the proposed
+        // tracker change). Runs BEFORE any push in a sync pipeline; a fail verdict
+        // or an unreadable scan input exits non-zero so nothing downstream commits
+        // or pushes. Findings name rule + item + field + content hash — never the
+        // matched content.
+        // -----------------------------------------------------------------------
+        api.registerCommand({
+            name: "github gate",
+            description: "Fail-closed privacy gate over the proposed tracker change (the staged/working/untracked diff under the resolved pm tracker path, or an explicit --diff file). Fails on credentials (GitHub/npm/AWS/Slack/OpenAI/Anthropic tokens, generic bearers, private-key blocks, high-entropy secret assignments), personal data (non-noreply emails, phone numbers), and host paths (absolute local filesystem paths, home-directory usernames). Reviewed false positives are allowlisted by content hash. Unreadable input or a scanner error fails. Read-only; never mutates anything. Use --json for machine output.",
+            intent: "verify a proposed tracker change before any public branch push",
+            examples: [
+                "pm github gate",
+                "pm github gate --json",
+                "pm github gate --diff pm-sync.patch",
+                "pm github gate --allowlist .pm-github-gate-allowlist.json",
+            ],
+            flags: GATE_FLAGS,
+            failure_hints: [
+                "Run inside the repository holding the pm tracker, or pass --diff <file> for an explicit unified diff.",
+                "A finding names the rule, item, field, and the sha256 of the matched content; allowlist that hash in .pm-github-gate-allowlist.json with a written reason after review.",
+                "The gate scans only added lines — removed content cannot publish anything new.",
+                "pm github import --gate composes this gate into an import: plan completeness and provenance idempotency are verified before the write, the scan runs after it.",
+            ],
+            async run(ctx) {
+                const diffFile = optionString(ctx.options, "diff");
+                const allowlistFile = optionString(ctx.options, "allowlist");
+                const report = runCommandTrackerGate({
+                    pmRoot: ctx.pm_root,
+                    ...(diffFile ? { diffFile } : {}),
+                    ...(allowlistFile ? { allowlistFile } : {}),
+                });
+                if (ctx.global.json !== true) {
+                    for (const line of formatGateReport(report))
+                        console.error(line);
+                }
+                if (report.verdict === "fail") {
+                    throw new CommandError(JSON.stringify({ ...report, error: "pm github gate: FAIL" }), EXIT_CODE.GENERIC_FAILURE);
+                }
+                return report;
+            },
+        });
+        // -----------------------------------------------------------------------
         // command — `pm github validate` (diagnostics: gh/token/repo reachability)
         // -----------------------------------------------------------------------
         api.registerCommand({
@@ -4152,7 +4483,7 @@ export default defineExtension({
             ],
             async run(ctx) {
                 const report = await runValidate(ctx);
-                const jsonMode = ctx.global?.json === true;
+                const jsonMode = ctx.global.json === true;
                 if (!jsonMode) {
                     for (const line of report.messages)
                         console.error(line);