pm-github 2026.7.18 → 2026.7.21

package/dist/index.js

@@ -13,6 +13,9 @@
 // Issues use the REST API; Projects v2 is GraphQL-only (see the Projects v2
 // section below and the pure plan/mapping logic in ./projects.ts).
 import https from "node:https";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
 import { spawnSync } from "node:child_process";
 async function loadPmComments() {
     const sdk = (await import("@unbrained/pm-cli/sdk"));
@@ -472,6 +475,215 @@ export function indexByProvenance(items) {
     return index;
 }
 // ---------------------------------------------------------------------------
+// Atomic GitHub issue import (pm-cli >= 2026.7.20 commitItemMutations)
+// ---------------------------------------------------------------------------
+const ATOMIC_IMPORT_PREFIX = "github-import-";
+let cachedCommitItemMutations;
+function assertSdkFunction(fn, exportName) {
+    if (typeof fn !== "function") {
+        throw new CommandError(`--atomic requires @unbrained/pm-cli>=2026.7.20 with the commitItemMutations SDK primitive, but the installed SDK does not export ${exportName} as a function. Upgrade @unbrained/pm-cli to >=2026.7.20.`, EXIT_CODE.USAGE);
+    }
+    return fn;
+}
+async function loadAtomicSdk(importSdk = () => import("@unbrained/pm-cli/sdk")) {
+    try {
+        return await importSdk();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new CommandError(`--atomic requires @unbrained/pm-cli>=2026.7.20, but the SDK could not be imported: ${msg}. Install or upgrade @unbrained/pm-cli.`, EXIT_CODE.USAGE);
+    }
+}
+/** Resolve the atomic bulk-mutation helper lazily so normal imports stay compatible. */
+export async function resolveCommitItemMutations(importSdk) {
+    if (importSdk) {
+        const mod = await loadAtomicSdk(importSdk);
+        return assertSdkFunction(mod.commitItemMutations, "commitItemMutations");
+    }
+    if (cachedCommitItemMutations)
+        return cachedCommitItemMutations;
+    const mod = await loadAtomicSdk();
+    cachedCommitItemMutations = assertSdkFunction(mod.commitItemMutations, "commitItemMutations");
+    return cachedCommitItemMutations;
+}
+async function resolveAtomicSdkFunctions(opts) {
+    const needsSdk = !opts.commitItemMutations || !opts.normalizeItemId || !opts.readSettings;
+    const mod = needsSdk ? await loadAtomicSdk() : undefined;
+    return {
+        commitItemMutations: opts.commitItemMutations ?? assertSdkFunction(mod?.commitItemMutations, "commitItemMutations"),
+        normalizeItemId: opts.normalizeItemId ?? assertSdkFunction(mod?.normalizeItemId, "normalizeItemId"),
+        readSettings: opts.readSettings ?? assertSdkFunction(mod?.readSettings, "readSettings"),
+    };
+}
+/**
+ * Derive an order-independent transaction id from the desired import state and
+ * exact ordered mutation plan. Content or target changes produce a fresh
+ * transaction; a reordered retry of the same plan resumes the durable journal.
+ */
+export function deriveAtomicTransactionId(repo, entries, mutations) {
+    const canonical = [...entries]
+        .sort((a, b) => a.issueNumber - b.issueNumber)
+        .map((entry) => ({
+        issueNumber: entry.issueNumber,
+        title: entry.title,
+        itemType: entry.itemType,
+        status: entry.status,
+        description: entry.description,
+        body: entry.body,
+        tags: [...entry.tags].sort(),
+        assignee: entry.assignee ?? null,
+        milestone: entry.milestone ?? null,
+    }));
+    const digest = crypto
+        .createHash("sha256")
+        .update(repo.toLowerCase())
+        .update("\x1f")
+        .update(JSON.stringify(canonical))
+        .update("\x1f")
+        // Recovery requires the exact ordered step plan. Include targets and
+        // options so a changed id_prefix or provenance match gets a fresh journal
+        // instead of colliding with an incompatible prior attempt.
+        .update(JSON.stringify(mutations))
+        .digest("hex")
+        .slice(0, 16);
+    return `${ATOMIC_IMPORT_PREFIX}${digest}`;
+}
+/** Stable create id keyed by the external GitHub issue, never by fetch order. */
+export function deriveAtomicItemId(repo, issueNumber, idPrefix, normalizeItemId) {
+    const repoToken = crypto
+        .createHash("sha256")
+        .update(repo.toLowerCase())
+        .digest("hex")
+        .slice(0, 12);
+    return normalizeItemId(`github-${repoToken}-${issueNumber}`, idPrefix);
+}
+/** Map one rendered import entry to its reversible SDK mutation sequence. */
+export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemId) {
+    const sharedOptions = {
+        title: entry.title,
+        type: entry.itemType,
+        description: entry.description,
+        body: entry.body,
+        tags: entry.tags.join(","),
+        ...(entry.assignee ? { assignee: entry.assignee } : {}),
+        ...(entry.milestone ? { sprint: entry.milestone } : {}),
+    };
+    const managedItemId = deriveAtomicItemId(repo, entry.issueNumber, idPrefix, normalizeItemId);
+    // A missing match and a match at our deterministic external-key id use the
+    // SAME create+update upsert plan. This is essential for crash recovery: if a
+    // prior attempt stopped after create, the next provenance scan sees that
+    // item, but commitItemMutations must still receive the original plan. The
+    // create step treats an existing stable id as already applied; update then
+    // makes later content-bearing transactions refresh the item normally.
+    if (!entry.match?.id || entry.match.id === managedItemId) {
+        const createStatus = entry.status === "closed" ? "open" : entry.status;
+        const mutations = [{
+                op: "create",
+                id: managedItemId,
+                options: { ...sharedOptions, status: createStatus },
+            }, {
+                op: "update",
+                id: managedItemId,
+                options: {
+                    ...sharedOptions,
+                    ...(entry.status !== "closed" ? { status: entry.status } : {}),
+                },
+            }];
+        if (entry.status === "closed") {
+            mutations.push({
+                op: "close",
+                id: managedItemId,
+                reason: `GitHub issue #${entry.issueNumber} closed`,
+            });
+        }
+        return {
+            itemId: managedItemId,
+            mutations,
+        };
+    }
+    const itemId = entry.match.id;
+    const updateOptions = { ...sharedOptions };
+    // close has a dedicated mutation so its reason is preserved. Every other
+    // transition (open/reopen/canceled) is safely reversible as part of update.
+    if (entry.status !== "closed") {
+        updateOptions.status = entry.status;
+    }
+    const mutations = [{
+            op: "update",
+            id: itemId,
+            options: updateOptions,
+        }];
+    if (entry.status === "closed") {
+        mutations.push({
+            op: "close",
+            id: itemId,
+            reason: `GitHub issue #${entry.issueNumber} closed`,
+        });
+    }
+    return { itemId, mutations };
+}
+/** Commit a complete issue-import batch under one crash-resumable transaction. */
+export async function importGithubAtomic(pmRoot, repo, entries, opts = {}) {
+    const { commitItemMutations: commit, normalizeItemId, readSettings, } = await resolveAtomicSdkFunctions(opts);
+    let idPrefix = "pm-";
+    try {
+        const settings = await readSettings(pmRoot);
+        if (settings?.id_prefix)
+            idPrefix = String(settings.id_prefix);
+    }
+    catch {
+        // Match normal import resilience: an unreadable optional setting falls
+        // back to the canonical prefix; the mutation still validates the tracker.
+    }
+    const mutations = [];
+    const itemIds = new Map();
+    // The transaction journal fingerprints the ordered step plan. Canonicalize
+    // by the stable GitHub issue number so a retry whose API page/order changed
+    // supplies the exact same plan as well as the same transaction id.
+    for (const entry of [...entries].sort((a, b) => a.issueNumber - b.issueNumber)) {
+        const planned = buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemId);
+        itemIds.set(entry.issueNumber, planned.itemId);
+        mutations.push(...planned.mutations);
+    }
+    const transactionId = deriveAtomicTransactionId(repo, entries, mutations);
+    try {
+        const result = await commit({
+            pmRoot,
+            transactionId,
+            author: opts.atomicAuthor ?? "pm-github",
+            mutations,
+            // This option selects how CREATE steps are compensated. The SDK's
+            // commitItemMutations contract independently snapshots and version-
+            // restores every UPDATE and CLOSE step (covered by the mixed rollback
+            // integration test below this implementation).
+            createCompensation: "delete",
+        });
+        // A recovered journal may include work applied by the interrupted process
+        // as well as steps resumed now. The SDK intentionally returns the durable
+        // final results, not a per-invocation delta, so create/update counts cannot
+        // be reconstructed truthfully. Report the recovered batch separately.
+        const recovered = Boolean(result?.recovered);
+        return {
+            transactionId,
+            recovered,
+            imported: recovered ? 0 : entries.filter((entry) => !entry.match?.id).length,
+            updated: recovered ? 0 : entries.filter((entry) => Boolean(entry.match?.id)).length,
+            ...(recovered ? { recoveredItems: entries.length } : {}),
+            itemIds,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(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);
+        }
+        if (err instanceof Error && err.name === "WorkspaceTransactionInterruptedError") {
+            throw new CommandError(`Atomic GitHub import was interrupted. Its durable journal is resumable; retry the same import to continue transaction ${transactionId}. Underlying error: ${msg}`, EXIT_CODE.GENERIC_FAILURE);
+        }
+        throw new CommandError(`Atomic GitHub import failed after the SDK completed its normal compensation path; no new partial committed state is expected. Transaction id: ${transactionId}. Underlying error: ${msg}`, EXIT_CODE.GENERIC_FAILURE);
+    }
+}
+// ---------------------------------------------------------------------------
 // Shared import core (used by both the legacy command and the importer)
 // ---------------------------------------------------------------------------
 // Build the GitHub issues list URL. `since`, `assignee`, `labels` and `state`
@@ -548,6 +760,324 @@ export function composeBody(issue, comments) {
     return body;
 }
 // ---------------------------------------------------------------------------
+// Cross-process comment-sync lock (serializes marker dedupe, pm-github-503u)
+// ---------------------------------------------------------------------------
+//
+// The native comment sync below does a read-markers-then-append sequence that
+// spans several pm CLI mutations. Each individual mutation is locked by the pm
+// CLI, but the check-then-act as a whole is not atomic across two concurrent
+// `pm github import` processes on the same workspace: both can observe a
+// GitHub comment id as absent and append it twice. The helper here closes that
+// race with a lockfile in the workspace's own locks/ dir, following the pm
+// CLI's locking convention (see core/lock/lock.js in pm-cli):
+//
+//   - location  <pm data dir>/locks/pm-github.comment-sync.<itemId>.lock — the
+//     same locks/ dir the pm CLI itself uses (gitignored runtime state), with
+//     a payload shape identical to the CLI's so `pm gc` can sweep our stale
+//     locks by their embedded ttl_seconds. The "pm-github.comment-sync."
+//     prefix keeps our namespace disjoint from the CLI's per-item mutation
+//     locks (<itemId>.lock): we hold our lock ACROSS several CLI mutations, so
+//     sharing a name would make the very mutations we wrap conflict with it.
+//   - acquire   fs.openSync(path, "wx") — atomic O_EXCL create on POSIX.
+//   - stale     a lock is broken (with a stderr warning) only when its owner
+//     is provably gone: the recorded owner PID is dead, or it equals our own
+//     PID (we know we don't hold it, so the PID was recycled). A lock with a
+//     LIVE owner is never age-broken — a slow-but-alive holder keeps its lock
+//     no matter how long it runs (a >TTL holder would otherwise lose the lock
+//     mid-append and the race would reopen). Only when the payload is missing
+//     or unparseable (caught mid-write, then abandoned) does the TTL (default
+//     5 min, age from file mtime) apply as the break criterion.
+//   - release   token-checked: each acquisition embeds a unique token in the
+//     payload and release() unlinks the file only while it still carries that
+//     token, so a holder whose lock was stale-broken (or swept by `pm gc`)
+//     can never unlink a successor's lock.
+//   - breaking  stale locks are removed under a breaker election (an O_EXCL
+//     `<lock>.break` sidecar): only the single election winner may unlink,
+//     and it re-verifies staleness under that mutex first — two concurrent
+//     breakers can therefore never double-break, and a breaker can never
+//     unlink a fresh lock that replaced the stale one it inspected.
+//   - contend   a live, fresh lock is waited out with jittered backoff up to a
+//     budget (default 30s). On timeout the caller reports "contended" and the
+//     comment sync for that item is SKIPPED (never run unlocked) — a wedged
+//     concurrent import can then cost a comment sync, recoverable by
+//     re-running import, but can never produce a duplicate comment. When the
+//     lock mechanism itself is unavailable (read-only fs etc.) the caller
+//     reports "degraded" and proceeds unlocked with a warning, matching the
+//     pre-lock best-effort behavior.
+export const IMPORT_LOCK_TTL_MS_DEFAULT = 5 * 60_000;
+export const IMPORT_LOCK_WAIT_MS_DEFAULT = 30_000;
+// Resolve the pm data dir (the dir holding settings.json and locks/) from the
+// pmRoot the extension host hands the command, which may be either the
+// workspace root (the dir containing .agents/pm) or the data dir itself — the
+// pm CLI accepts both for --path, and tests pass the workspace root.
+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. The
+// item id is sanitized defensively (pm ids are already filename-safe, but the
+// lock path must never become a traversal vector if that ever changes).
+export function importCommentSyncLockPath(pmRoot, itemId) {
+    const safe = itemId.replace(/[^A-Za-z0-9._-]/g, "_");
+    return path.join(resolvePmDataDir(pmRoot), "locks", `pm-github.comment-sync.${safe}.lock`);
+}
+function readImportLockPayload(lockPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(lockPath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isLockOwnerAlive(pid) {
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means the process exists but belongs to another user — still alive.
+        // ESRCH means no such process — the lock owner is gone.
+        return err?.code === "EPERM";
+    }
+}
+// A held lock is stale only when its owner is provably gone: the recorded
+// owner PID is dead (crash without release), or it equals our own PID (we
+// know we do not hold this lock, so the PID must have been recycled). A lock
+// with a LIVE recorded owner is never age-broken — breaking a slow-but-alive
+// holder mid-critical-section would reopen the duplicate-marker race this
+// lock exists to close. Only when there is no usable owner PID (payload
+// missing or unparseable — e.g. caught mid-write, then abandoned) does the
+// TTL apply, with age taken from the payload's created_at falling back to
+// the file mtime. (PID reuse can make a dead lock look alive and thus block
+// until the wait budget — conservative; it can never break a live one.)
+// Lock paths currently held by THIS process (any async task). Distinguishes a
+// same-pid payload that is legitimately ours (in-process contention → wait)
+// from a leftover written by a dead process whose PID we inherited (→ break).
+const heldImportLocks = new Set();
+function importLockStaleReason(lockPath, payload, mtimeMs, ttlMs) {
+    const pid = payload?.pid;
+    if (typeof pid === "number" && Number.isInteger(pid) && pid > 0) {
+        if (pid === process.pid) {
+            // Our own PID: either another async task in THIS process holds it (the
+            // in-process race the caller serializes too — contend, don't break), or
+            // we provably don't hold it and the PID was recycled by a dead owner.
+            return heldImportLocks.has(lockPath)
+                ? undefined
+                : `owner pid ${pid} is this process but the lock is not held in-process (pid recycled, lock abandoned)`;
+        }
+        return isLockOwnerAlive(pid) ? undefined : `owner pid ${pid} is dead`;
+    }
+    const createdMs = payload ? Date.parse(payload.created_at) : Number.NaN;
+    const ageBase = Number.isFinite(createdMs) ? createdMs : mtimeMs;
+    if (!Number.isFinite(ageBase) || Date.now() - ageBase > ttlMs) {
+        return `no usable owner pid and older than TTL ${Math.round(ttlMs / 1000)}s`;
+    }
+    return undefined;
+}
+const IMPORT_LOCK_INITIAL_BACKOFF_MS = 25;
+const IMPORT_LOCK_MAX_BACKOFF_MS = 200;
+const IMPORT_LOCK_MAX_STALE_BREAKS = 3;
+// A breaker's critical section is a handful of syscalls (re-stat, re-read,
+// unlink) — a crashed breaker's sidecar goes stale in seconds, not minutes.
+export const IMPORT_LOCK_BREAKER_TTL_MS = 10_000;
+// Break a stale lock under a breaker election so the unlink can never race
+// another breaker: two contenders may both judge the same file stale, but
+// without mutual exclusion the slower one would execute its unlink AFTER the
+// winner already re-created a fresh, live lock — silently unlinking that
+// replacement and letting both proceed (the exact double-acquire this module
+// exists to prevent). The election is an O_EXCL sidecar (`<lock>.break`):
+// only its single winner may unlink, and it re-verifies staleness under the
+// mutex first, so a lock that became live since the caller's check survives.
+// Returns true when the stale lock was removed (caller should retry acquire
+// immediately), false when the election was lost or the lock is live again
+// (caller should fall through to the normal wait/backoff).
+function breakStaleImportLock(lockPath, ttlMs, reason) {
+    const breakerPath = `${lockPath}.break`;
+    let bfd;
+    try {
+        bfd = fs.openSync(breakerPath, "wx");
+    }
+    catch (err) {
+        if (err?.code === "EEXIST") {
+            // Another breaker is active. If IT crashed mid-break, its sidecar is
+            // old — clear it and let the next iteration re-run the election.
+            try {
+                if (Date.now() - fs.statSync(breakerPath).mtimeMs > IMPORT_LOCK_BREAKER_TTL_MS) {
+                    fs.unlinkSync(breakerPath);
+                }
+            }
+            catch {
+                // Sidecar vanished (election finished) — retry normally.
+            }
+        }
+        return false;
+    }
+    try {
+        fs.closeSync(bfd);
+        // Re-verify under the mutex: the lock we judged stale may have been
+        // broken and re-acquired by a live owner since we looked at it.
+        let payload;
+        let mtimeMs = Number.NaN;
+        try {
+            mtimeMs = fs.statSync(lockPath).mtimeMs;
+            payload = readImportLockPayload(lockPath);
+        }
+        catch {
+            return true; // already gone — acquire can proceed immediately
+        }
+        if (!importLockStaleReason(lockPath, payload, mtimeMs, ttlMs))
+            return false;
+        console.error(`pm-github: breaking stale comment-sync lock ${lockPath} (${reason})`);
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch {
+            // Already gone.
+        }
+        return true;
+    }
+    finally {
+        try {
+            fs.unlinkSync(breakerPath);
+        }
+        catch {
+            // Best-effort: an aged-out sidecar may have been cleared by a peer.
+        }
+    }
+}
+// Acquire the cross-process comment-sync lock for one item. Never throws:
+// every failure mode maps to one of the three acquisition statuses so the
+// caller can decide how to degrade. `ttlMs`/`waitMs` are injectable for tests.
+export async function acquireImportLock(pmRoot, itemId, opts = {}) {
+    const ttlMs = opts.ttlMs ?? IMPORT_LOCK_TTL_MS_DEFAULT;
+    const waitMs = opts.waitMs ?? IMPORT_LOCK_WAIT_MS_DEFAULT;
+    let lockPath;
+    try {
+        lockPath = importCommentSyncLockPath(pmRoot, itemId);
+        fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`pm-github: comment-sync lock unavailable (${msg}) — proceeding without cross-process serialization`);
+        return { status: "degraded" };
+    }
+    const payload = {
+        id: path.basename(lockPath, ".lock"),
+        pid: process.pid,
+        owner: "pm-github",
+        token: crypto.randomUUID(),
+        created_at: new Date().toISOString(),
+        ttl_seconds: Math.ceil(ttlMs / 1000),
+    };
+    const startedAt = Date.now();
+    let backoffMs = IMPORT_LOCK_INITIAL_BACKOFF_MS;
+    let staleBreaks = 0;
+    for (;;) {
+        let fd;
+        try {
+            fd = fs.openSync(lockPath, "wx");
+            fs.writeFileSync(fd, `${JSON.stringify(payload, null, 2)}\n`);
+            fs.closeSync(fd);
+            fd = undefined;
+            heldImportLocks.add(lockPath);
+            let released = false;
+            return {
+                status: "acquired",
+                lock: {
+                    path: lockPath,
+                    release() {
+                        if (released)
+                            return;
+                        released = true;
+                        heldImportLocks.delete(lockPath);
+                        try {
+                            // Token check: only unlink the file while it is still OUR lock.
+                            // If it was stale-broken or gc-swept and re-acquired, the path
+                            // now holds the successor's lock — leave it alone.
+                            const current = readImportLockPayload(lockPath);
+                            if (current?.token !== payload.token)
+                                return;
+                            fs.unlinkSync(lockPath);
+                        }
+                        catch {
+                            // Best-effort: already gone (stale-broken by someone else, gc).
+                        }
+                    },
+                },
+            };
+        }
+        catch (err) {
+            if (fd !== undefined) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch {
+                    // Ignore close errors on the failure path.
+                }
+                // We created the lockfile but failed to write/close it. Remove the
+                // empty/partial file so other processes are not blocked until the
+                // TTL expires on a lock that was never validly held.
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch {
+                    // Best-effort: already gone.
+                }
+            }
+            const code = err?.code;
+            if (code !== "EEXIST") {
+                const msg = err instanceof Error ? err.message : String(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.
+            let existing;
+            let mtimeMs = Number.NaN;
+            try {
+                mtimeMs = fs.statSync(lockPath).mtimeMs;
+                existing = readImportLockPayload(lockPath);
+            }
+            catch {
+                continue;
+            }
+            const staleReason = importLockStaleReason(lockPath, existing, mtimeMs, ttlMs);
+            if (staleReason && staleBreaks < IMPORT_LOCK_MAX_STALE_BREAKS) {
+                staleBreaks++;
+                if (breakStaleImportLock(lockPath, ttlMs, staleReason))
+                    continue;
+                // Lost the breaker election or the lock turned out live on re-check —
+                // fall through to the normal wait/backoff below.
+            }
+            const elapsedMs = Date.now() - startedAt;
+            if (elapsedMs >= waitMs)
+                return { status: "contended" };
+            // Jittered backoff, mirroring the pm CLI's lock wait (0.5x–1.5x jitter).
+            const jittered = Math.max(1, Math.round(backoffMs * (0.5 + Math.random())));
+            await sleep(Math.min(jittered, waitMs - elapsedMs));
+            backoffMs = Math.min(backoffMs * 2, IMPORT_LOCK_MAX_BACKOFF_MS);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
 // Native comment sync (GitHub issue comments → pm comments collection)
 // ---------------------------------------------------------------------------
 //
@@ -602,45 +1132,65 @@ export function parseCreatedItemId(stdout) {
 // duplicates. Each GitHub comment becomes one pm comment authored by the
 // GitHub login. Failures are logged and never abort the import.
 //
-// Known limitation (tracked in pm-github-503u): the read-markers-then-append
-// sequence is not atomic across processes. Two concurrent imports of the same
-// repository into the same workspace can both observe a comment id as absent
-// and append it twice. Individual appends are still atomic (pm CLI locks per
-// mutation), so the worst case is a duplicate comment, never corruption.
+// Concurrency (pm-github-503u, limitation lifted): the read-markers-then-append
+// critical section is serialized across processes by a per-item lockfile (see
+// acquireImportLock above), so two concurrent `pm github import` runs against
+// the same workspace can no longer both observe a comment id as absent and
+// append it twice. The lock is per ITEM, not per import run: unrelated issues
+// in concurrent imports still sync in parallel, and only the one item whose
+// comments are actively being synced is serialized — the smallest scope that
+// closes the race. Stale locks (older than the TTL or owned by a dead PID) are
+// broken with a stderr warning. If a live concurrent import holds the lock
+// past the wait budget, this item's comment sync is skipped with a warning
+// (never run unlocked, so a wedged peer can cost a sync — recoverable on the
+// next import — but never cause a duplicate); if the lock mechanism itself is
+// unavailable the sync proceeds unlocked as before, also with a warning.
 export async function syncGithubCommentsToAnnotations(itemId, comments, pmRoot, issueNumber) {
     if (comments.length === 0)
         return { added: 0, skipped: 0 };
-    let pmComments;
-    let existing = [];
-    try {
-        pmComments = await loadPmComments();
-        const list = await pmComments(itemId, {}, { pmRoot });
-        existing = (list?.comments ?? []);
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.error(`#${issueNumber}: could not read existing comments for ${itemId} — ${msg}`);
+    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 };
     }
-    const synced = extractSyncedCommentIds(existing);
-    let added = 0;
-    let skipped = 0;
-    for (const c of comments) {
-        if (synced.has(c.id)) {
-            skipped++;
-            continue;
-        }
-        const author = c.user?.login ?? "github";
+    const release = acquisition.status === "acquired" ? () => acquisition.lock.release() : () => { };
+    try {
+        let pmComments;
+        let existing = [];
         try {
-            await pmComments(itemId, { add: buildCommentText(c), author }, { pmRoot });
-            added++;
+            pmComments = await loadPmComments();
+            const list = await pmComments(itemId, {}, { pmRoot });
+            existing = (list?.comments ?? []);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            console.error(`#${issueNumber}: comment ${c.id} sync failed — ${msg}`);
+            console.error(`#${issueNumber}: could not read existing comments for ${itemId} — ${msg}`);
+            return { added: 0, skipped: 0 };
         }
+        const synced = extractSyncedCommentIds(existing);
+        let added = 0;
+        let skipped = 0;
+        for (const c of comments) {
+            if (synced.has(c.id)) {
+                skipped++;
+                continue;
+            }
+            const author = c.user?.login ?? "github";
+            try {
+                await pmComments(itemId, { add: buildCommentText(c), author }, { pmRoot });
+                added++;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(`#${issueNumber}: comment ${c.id} sync failed — ${msg}`);
+            }
+        }
+        return { added, skipped };
+    }
+    finally {
+        release();
     }
-    return { added, skipped };
 }
 // A draft PR is an issue that is both a pull request and flagged `draft: true`.
 // (Plain issues are never drafts.)
@@ -706,6 +1256,7 @@ export function parseImportOptions(options) {
         commentsMode,
         itemType: optionString(options, "type") || "Issue",
         dryRun: optionEnabled(options, "dry-run", "dryRun"),
+        atomic: optionEnabled(options, "atomic"),
     };
 }
 // Spawn the `pm` CLI with the given argv and return a normalized ok/stdout/stderr
@@ -715,21 +1266,63 @@ function pmRun(args) {
     const result = spawnSync("pm", args, { encoding: "utf-8" });
     return { ok: result.status === 0, stderr: result.stderr || "", stdout: result.stdout || "" };
 }
+async function prepareGithubImport(issue, repo, opts, token, match, fetchIssueComments = fetchComments) {
+    const title = issue.title.trim();
+    if (!title)
+        return undefined;
+    const kind = issue.pull_request ? "PR" : "issue";
+    const labels = issue.labels.map((label) => label.name).filter(Boolean);
+    const tag = provenanceTag(repo, issue.number);
+    const ghAuthorTag = authorTag(issue);
+    const author = issue.user?.login;
+    const syncAnnotations = opts.commentsMode === "annotations" || opts.commentsMode === "both";
+    const shouldFetchComments = opts.withComments || syncAnnotations;
+    const writeCommentsToBody = opts.commentsMode === "body" || opts.commentsMode === "both";
+    let comments = [];
+    if (shouldFetchComments) {
+        try {
+            comments = await fetchIssueComments(issue, repo, token);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`#${issue.number}: failed to fetch comments — ${msg}`);
+        }
+    }
+    return {
+        issueNumber: issue.number,
+        title,
+        itemType: opts.itemType,
+        status: mapState(issue.state, issue.state_reason),
+        description: `GH ${kind} #${issue.number}: ${issue.html_url}` +
+            (author ? ` · author @${author}` : "") +
+            (issue.state_reason ? ` · state reason ${issue.state_reason}` : "") +
+            (issue.created_at ? ` · created ${issue.created_at}` : "") +
+            (issue.updated_at ? ` · updated ${issue.updated_at}` : ""),
+        body: writeCommentsToBody ? composeBody(issue, comments) : (issue.body || ""),
+        tags: [...labels, tag, ...(ghAuthorTag ? [ghAuthorTag] : [])],
+        assignee: issue.assignee?.login,
+        milestone: issue.milestone?.title,
+        comments,
+        syncAnnotations,
+        match,
+    };
+}
 // Run the full import flow. Idempotent: items already linked (provenance tag)
 // to a fetched issue are UPDATEd; new issues are created. Returns a structured
 // result; throws CommandError (with a semantic exitCode) on failure.
-async function runImport(repoArg, pmRoot, opts) {
+export async function runImport(repoArg, pmRoot, 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>] " +
-            "[--milestone <name>] [--include-prs] [--skip-drafts] [--with-comments] [--comments-mode body|annotations|both]", EXIT_CODE.USAGE);
+            "[--milestone <name>] [--include-prs] [--skip-drafts] [--with-comments] " +
+            "[--comments-mode body|annotations|both] [--atomic]", EXIT_CODE.USAGE);
     }
     const repo = repoArg;
-    const token = resolveGitHubToken();
+    const token = (dependencies.resolveToken ?? resolveGitHubToken)();
     console.error(`Fetching issues from ${repo}…${token ? "" : " (unauthenticated — 60 req/hr)"}`);
     let fetched;
     try {
-        fetched = await fetchAllIssues(repo, opts, token);
+        fetched = await (dependencies.fetchIssues ?? fetchAllIssues)(repo, opts, token);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -742,59 +1335,100 @@ async function runImport(repoArg, pmRoot, opts) {
     const filtered = applyClientFilters(fetched, opts);
     if (filtered.length === 0) {
         console.error("No issues found.");
+        if (opts.atomic && opts.dryRun) {
+            return {
+                dryRun: true,
+                wouldImport: 0,
+                wouldUpdate: 0,
+                wouldSkip: 0,
+                atomic: true,
+            };
+        }
         return { imported: 0, updated: 0, skipped: 0 };
     }
     console.error(`Found ${filtered.length} issue(s).`);
     // Build the idempotency index once up-front.
-    const existing = opts.dryRun ? new Map() : indexByProvenance(readPmItems(pmRoot));
+    const shouldMatchExisting = !opts.dryRun || opts.atomic;
+    const existing = shouldMatchExisting
+        ? indexByProvenance((dependencies.readItems ?? readPmItems)(pmRoot))
+        : new Map();
     let imported = 0;
     let updated = 0;
     let skipped = 0;
+    if (opts.atomic) {
+        const prepared = [];
+        for (const issue of filtered) {
+            const entry = await prepareGithubImport(issue, repo, opts, token, existing.get(`${repo.toLowerCase()}#${issue.number}`), dependencies.fetchIssueComments);
+            if (!entry) {
+                skipped++;
+                continue;
+            }
+            prepared.push(entry);
+        }
+        if (prepared.length === 0) {
+            if (opts.dryRun) {
+                console.error(`[dry-run] Atomic plan would import 0, update 0, skip ${skipped}.`);
+                return {
+                    dryRun: true,
+                    wouldImport: 0,
+                    wouldUpdate: 0,
+                    wouldSkip: skipped,
+                    atomic: true,
+                };
+            }
+            throw new CommandError(`Imported 0 issue(s); ${skipped} failed.`, EXIT_CODE.GENERIC_FAILURE);
+        }
+        if (opts.dryRun) {
+            imported = prepared.filter((entry) => !entry.match?.id).length;
+            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 plan would import ${imported}, update ${updated}, skip ${skipped}.`);
+            return {
+                dryRun: true,
+                wouldImport: imported,
+                wouldUpdate: updated,
+                wouldSkip: skipped,
+                atomic: true,
+            };
+        }
+        const result = await (dependencies.commitAtomic ?? importGithubAtomic)(pmRoot, repo, prepared);
+        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);
+            }
+        }
+        if (result.recovered) {
+            console.error(`Atomic import recovered transaction ${result.transactionId} covering ${result.recoveredItems ?? prepared.length} item(s).`);
+        }
+        else {
+            console.error(`Atomically imported ${result.imported} new, updated ${result.updated} existing, skipped ${skipped}.`);
+        }
+        // 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.
+        return {
+            transactionId: result.transactionId,
+            recovered: result.recovered,
+            imported: result.imported,
+            updated: result.updated,
+            ...(result.recoveredItems !== undefined ? { recoveredItems: result.recoveredItems } : {}),
+            skipped,
+            atomic: true,
+        };
+    }
     for (const issue of filtered) {
-        const title = issue.title.trim();
-        if (!title) {
+        const prepared = await prepareGithubImport(issue, repo, opts, token, existing.get(`${repo.toLowerCase()}#${issue.number}`), dependencies.fetchIssueComments);
+        if (!prepared) {
             skipped++;
             continue;
         }
-        const kind = issue.pull_request ? "PR" : "issue";
         const labels = issue.labels.map((l) => l.name).filter(Boolean);
-        const tag = provenanceTag(repo, issue.number);
-        const ghAuthorTag = authorTag(issue);
-        const tags = [...labels, tag, ...(ghAuthorTag ? [ghAuthorTag] : [])];
-        const status = mapState(issue.state, issue.state_reason);
-        const assignee = issue.assignee?.login;
-        const milestone = issue.milestone?.title;
-        const key = `${repo.toLowerCase()}#${issue.number}`;
-        const match = existing.get(key);
-        // GitHub provenance lives in the description (human-readable) and the
-        // declared schema fields (github_url/github_number/github_state/
-        // github_author/github_created_at/github_updated_at). Author + timestamps
-        // are appended additively so a re-import keeps them current.
-        const author = issue.user?.login;
-        const description = `GH ${kind} #${issue.number}: ${issue.html_url}` +
-            (author ? ` · author @${author}` : "") +
-            (issue.state_reason ? ` · state reason ${issue.state_reason}` : "") +
-            (issue.created_at ? ` · created ${issue.created_at}` : "") +
-            (issue.updated_at ? ` · updated ${issue.updated_at}` : "");
-        // Comments are fetched when --with-comments asks for the legacy body
-        // embedding OR when --comments-mode targets the native comments collection
-        // (annotations/both). In default mode (body + no --with-comments) nothing is
-        // fetched, keeping import output byte-identical to pre-2026.7.14 behavior.
-        const syncAnnotations = opts.commentsMode === "annotations" || opts.commentsMode === "both";
-        const shouldFetchComments = opts.withComments || syncAnnotations;
-        // Comments land in the body only in body/both mode (the historical path).
-        const writeCommentsToBody = opts.commentsMode === "body" || opts.commentsMode === "both";
-        let comments = [];
-        if (shouldFetchComments) {
-            try {
-                comments = await fetchComments(issue, repo, token);
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                console.error(`#${issue.number}: failed to fetch comments — ${msg}`);
-            }
-        }
-        const body = writeCommentsToBody ? composeBody(issue, comments) : (issue.body || "");
+        const { title, status, assignee, milestone, match, description, body, tags, comments, syncAnnotations, } = prepared;
         if (opts.dryRun) {
             console.error(`  [dry-run] #${issue.number} ${title} (${status}, ${labels.join(",")})`);
             imported++;
@@ -881,7 +1515,12 @@ async function runImport(repoArg, pmRoot, opts) {
     }
     if (opts.dryRun) {
         console.error(`[dry-run] Would import ${imported}, skip ${skipped}.`);
-        return { dryRun: true, wouldImport: imported, wouldSkip: skipped };
+        return {
+            dryRun: true,
+            wouldImport: imported,
+            wouldSkip: skipped,
+            ...(opts.atomic ? { atomic: true } : {}),
+        };
     }
     console.error(`Imported ${imported} new, updated ${updated} existing, skipped ${skipped}.`);
     if (imported === 0 && updated === 0 && skipped > 0) {
@@ -2035,6 +2674,7 @@ const IMPORT_FLAGS = [
     { long: "--with-comments", description: "Fetch issue comments and append them to the item body" },
     { long: "--include-comments", description: "Alias for --with-comments" },
     { 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: "--dry-run", description: "Preview without writing" },
     { long: "--type", value_name: "type", description: "Override pm item type (default: Issue)" },
 ];
@@ -2081,7 +2721,7 @@ const PROJECT_SYNC_FLAGS = [
 ];
 export default defineExtension({
     name: "pm-github",
-    version: "2026.7.18",
+    version: "2026.7.21",
     activate(api) {
         // -----------------------------------------------------------------------
         // schema — declare the GitHub provenance fields so the workspace knows them
@@ -2129,6 +2769,7 @@ export default defineExtension({
                 "pm github import owner/repo --since 7d",
                 "pm github import owner/repo --include-comments",
                 "pm github import owner/repo --comments-mode annotations",
+                "pm github import owner/repo --atomic",
                 "pm github import owner/repo --dry-run",
             ],
             flags: IMPORT_FLAGS,
@@ -2136,6 +2777,7 @@ export default defineExtension({
                 "Pass <owner/repo>, e.g. `pm github import unbraind/pm-cli`.",
                 "Set GITHUB_TOKEN/GH_TOKEN or run `gh auth login` for private repos / 5000 req/hr.",
                 "Re-running is safe: existing items are updated, not duplicated.",
+                "Use --atomic for a durable resumable journal with reverse compensation on ordinary failures.",
             ],
         });
         // -----------------------------------------------------------------------
@@ -2293,6 +2935,7 @@ export default defineExtension({
                 "pm gh-issues import unbraind/pm-cli --since 2026-01-01T00:00:00Z",
                 "pm github import owner/repo --with-comments",
                 "pm github import owner/repo --comments-mode annotations",
+                "pm github import owner/repo --atomic",
                 "pm github import owner/repo --dry-run",
             ],
             flags: IMPORT_FLAGS,
@@ -2300,6 +2943,7 @@ export default defineExtension({
                 "Pass <owner/repo>, e.g. `pm gh-issues import unbraind/pm-cli`.",
                 "Set GITHUB_TOKEN/GH_TOKEN or run `gh auth login` for private repos / 5000 req/hr.",
                 "Re-running is safe: existing items are updated, not duplicated.",
+                "Use --atomic for a durable resumable journal with reverse compensation on ordinary failures.",
             ],
             async run(ctx) {
                 return runImport(ctx.args[0], ctx.pm_root, parseImportOptions(ctx.options));