specrails-desktop 2.3.0 → 2.4.0

package/server/dist/jira/jira-sync-manager.js

@@ -0,0 +1,1014 @@
+"use strict";
+// Per-project Jira sync orchestrator. One instance lives on each ProjectContext
+// beside QueueManager/ChatManager. It owns:
+//   - the inbound poll loop (JQL high-water + overlap → materializer),
+//   - the durable outbox drainer (FIFO-per-issue, idempotency-first, error
+//     classification → retry / dead-letter / auth-pause),
+//   - the two write-back hooks: onRailLaunch (todo→In Progress) and onJobOutcome
+//     (Done / revert + completion comment),
+// and stays completely inert until the project configures a Jira connection.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JiraSyncManager = void 0;
+exports.backoffMs = backoffMs;
+exports.formatJqlDate = formatJqlDate;
+exports.buildCompletionComment = buildCompletionComment;
+const ticket_store_1 = require("../ticket-store");
+const jira_client_1 = require("./jira-client");
+const jira_backlog_config_1 = require("./jira-backlog-config");
+const jira_adf_1 = require("./jira-adf");
+const jira_materializer_1 = require("./jira-materializer");
+const jira_issue_fields_1 = require("./jira-issue-fields");
+const jira_status_resolver_1 = require("./jira-status-resolver");
+const jira_db_1 = require("./jira-db");
+const POLL_INTERVAL_MS = 60_000;
+const DRAIN_INTERVAL_MS = 10_000;
+const POLL_OVERLAP_MS = 2 * 60_000;
+const MAX_DRAIN_BATCH = 8;
+const SEARCH_FIELDS = ['summary', 'description', 'labels', 'status', 'priority', 'assignee', 'updated', 'issuetype', 'parent'];
+/** Local priority → Jira priority NAME (standard scheme; best-effort). A custom
+ *  scheme that rejects the name is retried without priority in executeUpdate. */
+const PRIORITY_TO_JIRA = {
+    critical: 'Highest',
+    high: 'High',
+    medium: 'Medium',
+    low: 'Low',
+};
+class JiraSyncManager {
+    db;
+    projectId;
+    projectPath;
+    broadcast;
+    fetchImpl;
+    notifyLocalWriteCb;
+    pollTimer = null;
+    drainTimer = null;
+    /** When set, the outbox is paused pending re-auth (401). */
+    authPaused = false;
+    constructor(opts) {
+        this.db = opts.db;
+        this.projectId = opts.projectId;
+        this.projectPath = opts.projectPath;
+        this.broadcast = opts.broadcast;
+        this.fetchImpl = opts.fetchImpl;
+        this.notifyLocalWriteCb = opts.notifyLocalWrite;
+        if (opts.startTimers !== false)
+            this.start();
+    }
+    /** Suppress the file-watcher echo for a local write we just made. */
+    notifyLocalWrite(revision) {
+        try {
+            this.notifyLocalWriteCb?.(revision);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    /** Late-bind the watcher notifier (the TicketWatcher is constructed after us). */
+    setLocalWriteNotifier(fn) {
+        this.notifyLocalWriteCb = fn;
+    }
+    // ─── Lifecycle ─────────────────────────────────────────────────────────────
+    /** True when this project has an enabled connection with a token. */
+    isActive() {
+        const conn = (0, jira_db_1.getConnection)(this.db, this.projectId);
+        return !!conn && conn.enabled && (0, jira_db_1.getDecryptedToken)(this.db, this.projectId) !== null;
+    }
+    start() {
+        // Only arm timers for projects that actually have a Jira connection — a
+        // non-Jira project must not wake its event loop every 10s for a no-op.
+        let conn = null;
+        try {
+            conn = (0, jira_db_1.getConnection)(this.db, this.projectId);
+        }
+        catch {
+            /* tables may not exist on a stale DB */
+        }
+        if (!conn)
+            return;
+        // Recover any inflight ops left by a crash, then arm timers if active.
+        try {
+            (0, jira_db_1.resetInflight)(this.db);
+        }
+        catch {
+            /* table may not exist on a stale DB */
+        }
+        if (this.pollTimer || this.drainTimer)
+            return;
+        this.pollTimer = setInterval(() => {
+            void this.pollOnce().catch(() => undefined);
+        }, POLL_INTERVAL_MS);
+        this.drainTimer = setInterval(() => {
+            void this.drainOnce().catch(() => undefined);
+        }, DRAIN_INTERVAL_MS);
+        // Unref so timers never keep the process alive on shutdown.
+        this.pollTimer.unref?.();
+        this.drainTimer.unref?.();
+    }
+    stop() {
+        if (this.pollTimer)
+            clearInterval(this.pollTimer);
+        if (this.drainTimer)
+            clearInterval(this.drainTimer);
+        this.pollTimer = null;
+        this.drainTimer = null;
+    }
+    buildClient() {
+        const conn = (0, jira_db_1.getConnection)(this.db, this.projectId);
+        if (!conn)
+            return null;
+        const token = (0, jira_db_1.getDecryptedToken)(this.db, this.projectId);
+        if (!token)
+            return null;
+        return new jira_client_1.JiraClient({
+            baseUrl: conn.baseUrl,
+            deployment: conn.deployment,
+            apiVersion: conn.apiVersion,
+            authScheme: conn.authScheme,
+            accountEmail: conn.accountEmail,
+            token,
+            fetchImpl: this.fetchImpl,
+        });
+    }
+    /**
+     * Discover the sprint custom-field id (schema gh-sprint). Returns the field
+     * id, 'none' when no sprint field exists, or null when it couldn't be
+     * determined (transient failure → caller leaves it unchecked to retry).
+     */
+    async discoverSprintField(client) {
+        const res = await client.getFields();
+        if (!res.ok)
+            return null;
+        const field = res.data.find((f) => f.schema?.custom === 'com.pyxis.greenhopper.jira:gh-sprint');
+        return field ? field.id : 'none';
+    }
+    // ─── Connect / disconnect ──────────────────────────────────────────────────
+    /**
+     * Validate a candidate connection (credential + project) and persist it on
+     * success. Writes the backlog-config so core treats the cache as read-only.
+     */
+    async connect(input) {
+        const detected = (0, jira_client_1.detectDeployment)(input.baseUrl);
+        const probe = new jira_client_1.JiraClient({
+            baseUrl: input.baseUrl,
+            deployment: detected.deployment,
+            apiVersion: detected.apiVersion,
+            authScheme: detected.authScheme,
+            accountEmail: input.accountEmail,
+            token: input.token,
+            fetchImpl: this.fetchImpl,
+        });
+        const me = await probe.myself();
+        if (!me.ok) {
+            return { ok: false, error: me.code === 'auth' ? 'Invalid Jira credentials' : `Connection failed: ${me.error}`, status: me.status };
+        }
+        const proj = await probe.getProject(input.jiraProjectKey);
+        if (!proj.ok) {
+            return {
+                ok: false,
+                error: proj.code === 'not_found' ? `Jira project "${input.jiraProjectKey}" not found or no access` : `Project check failed: ${proj.error}`,
+                status: proj.status,
+            };
+        }
+        const connection = (0, jira_db_1.upsertConnection)(this.db, {
+            projectId: this.projectId,
+            baseUrl: input.baseUrl.replace(/\/+$/, ''),
+            deployment: detected.deployment,
+            apiVersion: detected.apiVersion,
+            authScheme: detected.authScheme,
+            accountEmail: input.accountEmail,
+            jiraProjectKey: proj.data.key,
+            jiraProjectId: proj.data.id,
+            token: input.token,
+            enabled: true,
+            statusMap: input.statusMap ?? null,
+        });
+        if (input.discardStatus !== undefined) {
+            (0, jira_db_1.setDiscardStatus)(this.db, this.projectId, input.discardStatus);
+        }
+        (0, jira_backlog_config_1.writeJiraBacklogConfig)(this.projectPath);
+        // Discover the sprint custom-field id (best-effort) so sprint capture works
+        // from the first poll. Non-fatal — the poll re-discovers if this fails.
+        try {
+            const fieldId = await this.discoverSprintField(probe);
+            if (fieldId !== null)
+                (0, jira_db_1.setSprintFieldId)(this.db, this.projectId, fieldId);
+        }
+        catch {
+            /* non-fatal */
+        }
+        this.authPaused = false;
+        this.start();
+        // Kick an immediate first sync (best-effort).
+        void this.pollOnce().catch(() => undefined);
+        return { ok: true, connection: (0, jira_db_1.getConnection)(this.db, this.projectId) ?? connection };
+    }
+    throwawayClient(input) {
+        const detected = (0, jira_client_1.detectDeployment)(input.baseUrl);
+        return new jira_client_1.JiraClient({
+            baseUrl: input.baseUrl,
+            deployment: detected.deployment,
+            apiVersion: detected.apiVersion,
+            authScheme: detected.authScheme,
+            accountEmail: input.accountEmail,
+            token: input.token,
+            fetchImpl: this.fetchImpl,
+        });
+    }
+    /** Wizard step 1: validate credentials without persisting anything. */
+    async probeCredentials(input) {
+        const detected = (0, jira_client_1.detectDeployment)(input.baseUrl);
+        const me = await this.throwawayClient(input).myself();
+        if (!me.ok) {
+            return { ok: false, error: me.code === 'auth' ? 'Invalid email or token' : me.error, status: me.status };
+        }
+        return { ok: true, deployment: detected.deployment, displayName: me.data.displayName ?? me.data.emailAddress ?? null };
+    }
+    /** Wizard step 2: list the projects this credential can see. */
+    async discoverProjects(input) {
+        const res = await this.throwawayClient(input).searchProjects(input.query);
+        if (!res.ok)
+            return { ok: false, error: res.error, status: res.status };
+        return { ok: true, projects: res.data };
+    }
+    /** Wizard step 3 (optional): the chosen project's real status list for mapping. */
+    async discoverStatuses(input) {
+        const res = await this.throwawayClient(input).getProjectStatuses(input.projectKey);
+        if (!res.ok)
+            return { ok: false, error: res.error };
+        const seen = new Map();
+        for (const group of res.data) {
+            for (const s of group.statuses) {
+                if (!seen.has(s.id))
+                    seen.set(s.id, { id: s.id, name: s.name, category: s.statusCategory?.key ?? 'indeterminate' });
+            }
+        }
+        return { ok: true, statuses: Array.from(seen.values()) };
+    }
+    /** Pause/resume sync without losing config (hot-swap back to local specs). */
+    setEnabled(enabled) {
+        (0, jira_db_1.setConnectionEnabled)(this.db, this.projectId, enabled);
+        if (enabled) {
+            (0, jira_backlog_config_1.writeJiraBacklogConfig)(this.projectPath);
+            this.start();
+        }
+        else {
+            (0, jira_backlog_config_1.writeLocalBacklogConfig)(this.projectPath);
+        }
+    }
+    /** Configure (or clear) the status a discarded spec is moved to. */
+    setDiscardStatus(status) {
+        (0, jira_db_1.setDiscardStatus)(this.db, this.projectId, status);
+    }
+    /** Replace (or clear) the per-logical-state status map (post-connect edit). */
+    setStatusMap(statusMap) {
+        (0, jira_db_1.setStatusMap)(this.db, this.projectId, statusMap);
+    }
+    /**
+     * List the connected project's real statuses (for the post-connect "move on
+     * discard" picker). Uses the stored credentials — no creds needed from caller.
+     */
+    async listStatusesForConnection() {
+        const conn = (0, jira_db_1.getConnection)(this.db, this.projectId);
+        if (!conn)
+            return { ok: false, error: 'No Jira connection configured' };
+        const client = this.buildClient();
+        if (!client)
+            return { ok: false, error: 'No Jira credentials' };
+        const res = await client.getProjectStatuses(conn.jiraProjectKey);
+        if (!res.ok)
+            return { ok: false, error: res.error };
+        const seen = new Map();
+        for (const group of res.data) {
+            for (const s of group.statuses) {
+                if (!seen.has(s.id))
+                    seen.set(s.id, { id: s.id, name: s.name, category: s.statusCategory?.key ?? 'indeterminate' });
+            }
+        }
+        return { ok: true, statuses: Array.from(seen.values()) };
+    }
+    /** Remove the connection entirely and restore local backlog config. */
+    disconnect() {
+        (0, jira_db_1.deleteConnection)(this.db, this.projectId);
+        (0, jira_backlog_config_1.writeLocalBacklogConfig)(this.projectPath);
+        this.stop();
+    }
+    // ─── Create a spec in Jira (Add Spec when source = Jira) ───────────────────
+    /**
+     * Create a Jira issue for a new spec, materialize it into the local cache, and
+     * return the minted local `#id`. The issue type defaults to "Task" (the most
+     * universally present type); customers with no Task type can override later.
+     */
+    async createSpec(input) {
+        const conn = (0, jira_db_1.getConnection)(this.db, this.projectId);
+        if (!conn)
+            return { ok: false, error: 'No Jira connection configured' };
+        const client = this.buildClient();
+        if (!client)
+            return { ok: false, error: 'No Jira credentials' };
+        const created = await client.createIssue({
+            projectKey: conn.jiraProjectKey,
+            issueType: input.issueType ?? 'Task',
+            summary: input.title,
+            description: input.description,
+            labels: input.labels,
+            priority: input.priority,
+        });
+        if (!created.ok) {
+            if (created.code === 'auth')
+                this.onAuth401();
+            return { ok: false, error: created.error || 'Jira issue create failed', status: created.status };
+        }
+        // Fetch the full issue so the cache reflects the real status/fields.
+        const full = await client.getIssue(created.data.id, SEARCH_FIELDS);
+        const issue = full.ok
+            ? full.data
+            : { id: created.data.id, key: created.data.key, fields: { summary: input.title, labels: input.labels ?? [] } };
+        const r = (0, jira_materializer_1.upsertIssuesIntoStore)(this.db, this.projectPath, conn, [issue], new Set());
+        if (r.wrote)
+            this.notifyLocalWrite(r.revision);
+        const localId = r.changedLocalIds[0];
+        const t = readTicket(this.projectPath, localId);
+        if (t)
+            this.broadcast({ type: 'ticket_created', ticket: t, projectId: this.projectId, timestamp: t.updated_at });
+        return { ok: true, localId, jiraKey: created.data.key };
+    }
+    /**
+     * Promote an existing LOCAL ticket to a Jira issue (Add Spec on a Jira-backed
+     * project). Creates the issue, links it to the SAME local id (no new id minted,
+     * no duplicate ticket), and flips the cached ticket to `source:'jira'` with its
+     * key/url. Idempotent: a ticket already linked is a no-op. Best-effort — on
+     * failure the ticket simply stays local and the caller surfaces a warning.
+     */
+    async promoteTicketToJira(localId) {
+        if (!this.isActive())
+            return { ok: false, error: 'jira not active' };
+        const existing = (0, jira_db_1.getLinkByLocalId)(this.db, localId);
+        if (existing && !existing.tombstoned)
+            return { ok: true, jiraKey: existing.jiraKey, alreadyLinked: true };
+        const conn = (0, jira_db_1.getConnection)(this.db, this.projectId);
+        if (!conn)
+            return { ok: false, error: 'no jira connection' };
+        const client = this.buildClient();
+        if (!client)
+            return { ok: false, error: 'no jira credentials' };
+        const file = (0, ticket_store_1.resolveTicketStoragePath)(this.projectPath);
+        const ticket = (0, ticket_store_1.readStore)(file).tickets[String(localId)];
+        if (!ticket)
+            return { ok: false, error: 'ticket not found' };
+        const created = await client.createIssue({
+            projectKey: conn.jiraProjectKey,
+            issueType: 'Task',
+            summary: ticket.title,
+            description: ticket.description || undefined,
+            labels: ticket.labels,
+        });
+        if (!created.ok) {
+            if (created.code === 'auth')
+                this.onAuth401();
+            return { ok: false, error: created.error || 'jira issue create failed' };
+        }
+        (0, jira_db_1.insertLinkWithId)(this.db, {
+            localId,
+            jiraIssueId: created.data.id,
+            jiraKey: created.data.key,
+            jiraProjectId: conn.jiraProjectId,
+            deployment: conn.deployment,
+        });
+        let updated;
+        const promoteStore = (0, ticket_store_1.mutateStore)(file, (s) => {
+            const t = s.tickets[String(localId)];
+            if (t) {
+                t.source = 'jira';
+                t.jira_key = created.data.key;
+                t.jira_url = (0, jira_materializer_1.issueUrl)(conn.baseUrl, created.data.key);
+                t.updated_at = new Date().toISOString();
+                updated = t;
+            }
+        });
+        this.notifyLocalWrite(promoteStore.revision);
+        if (updated) {
+            this.broadcast({ type: 'ticket_updated', ticket: updated, projectId: this.projectId, timestamp: updated.updated_at });
+        }
+        return { ok: true, jiraKey: created.data.key };
+    }
+    // ─── Inbound poll ──────────────────────────────────────────────────────────
+    /** The set of local ids with a pending/inflight outbox op (status is frozen). */
+    frozenLocalIds() {
+        const rows = this.db
+            .prepare(`SELECT DISTINCT l.local_id AS localId
+           FROM jira_outbox o JOIN jira_links l ON l.jira_issue_id = o.jira_issue_id
+          WHERE o.state IN ('pending','inflight') AND o.op_type IN ('transition','update')`)
+            .all();
+        return new Set(rows.map((r) => r.localId));
+    }
+    /**
+     * Inbound poll. `full=true` ignores the high-water mark and re-fetches the
+     * whole backlog — used by the manual "Sync now" so it back-fills any fields
+     * the cache is missing (e.g. sprint/epic data added after the last sync).
+     */
+    async pollOnce(full = false) {
+        let conn = (0, jira_db_1.getConnection)(this.db, this.projectId);
+        if (!conn || !conn.enabled)
+            return null;
+        const client = this.buildClient();
+        if (!client)
+            return null;
+        // Lazily discover the sprint custom-field id for connections made before the
+        // feature existed (null = not yet checked). Persist 'none' when there's none.
+        if (conn.sprintFieldId === null) {
+            const fieldId = await this.discoverSprintField(client);
+            if (fieldId !== null) {
+                (0, jira_db_1.setSprintFieldId)(this.db, this.projectId, fieldId);
+                // First time we find a real sprint field on an ALREADY-synced connection:
+                // reset the high-water so this poll re-fetches every issue and back-fills
+                // the sprint (and epic) data the cache is missing. One-time full re-sync.
+                if (fieldId !== 'none' && conn.highWaterMs && conn.highWaterMs > 0) {
+                    (0, jira_db_1.setHighWater)(this.db, this.projectId, 0);
+                }
+                conn = (0, jira_db_1.getConnection)(this.db, this.projectId) ?? conn;
+            }
+        }
+        const searchFields = conn.sprintFieldId && conn.sprintFieldId !== 'none' ? [...SEARCH_FIELDS, conn.sprintFieldId] : SEARCH_FIELDS;
+        const frozen = this.frozenLocalIds();
+        let jql = `project = "${conn.jiraProjectKey}" ORDER BY updated ASC`;
+        if (!full && conn.highWaterMs && conn.highWaterMs > 0) {
+            const since = formatJqlDate(conn.highWaterMs - POLL_OVERLAP_MS);
+            jql = `project = "${conn.jiraProjectKey}" AND updated >= "${since}" ORDER BY updated ASC`;
+        }
+        let nextPageToken;
+        let totalUpserted = 0;
+        let maxUpdated = conn.highWaterMs ?? 0;
+        for (let page = 0; page < 50; page++) {
+            const res = await client.searchJql({ jql, fields: searchFields, nextPageToken, maxResults: 100 });
+            if (!res.ok) {
+                if (res.code === 'auth')
+                    this.onAuth401();
+                else
+                    this.broadcast({ type: 'jira.sync_error', projectId: this.projectId, reason: res.error });
+                return null;
+            }
+            const issues = res.data.issues ?? [];
+            if (issues.length > 0) {
+                const r = (0, jira_materializer_1.upsertIssuesIntoStore)(this.db, this.projectPath, conn, issues, frozen);
+                // Suppress the watcher echo for our own write (avoids the full-board
+                // refresh flicker). When nothing changed, `wrote` is false and we also
+                // skip the granular broadcasts below — the board stays perfectly still.
+                if (r.wrote)
+                    this.notifyLocalWrite(r.revision);
+                totalUpserted += r.upserted;
+                if (r.maxUpdatedMs > maxUpdated)
+                    maxUpdated = r.maxUpdatedMs;
+                for (const localId of r.changedLocalIds) {
+                    const t = readTicket(this.projectPath, localId);
+                    if (t)
+                        this.broadcast({ type: 'ticket_updated', ticket: t, projectId: this.projectId, timestamp: t.updated_at });
+                }
+            }
+            nextPageToken = res.data.nextPageToken;
+            if (!nextPageToken || issues.length === 0)
+                break;
+        }
+        if (maxUpdated > (conn.highWaterMs ?? 0))
+            (0, jira_db_1.setHighWater)(this.db, this.projectId, maxUpdated);
+        if (totalUpserted > 0)
+            this.broadcast({ type: 'jira.synced', projectId: this.projectId, upserted: totalUpserted, at: Date.now() });
+        return { upserted: totalUpserted };
+    }
+    // ─── Outbound write-back hooks ─────────────────────────────────────────────
+    /**
+     * Called from the rail-launch handler. For each Jira-linked ticket, enqueue an
+     * In Progress transition AND write in_progress into the local cache (because
+     * backlog-config write_access:false stops core from writing it). No-op for
+     * non-Jira projects / unlinked tickets.
+     */
+    onRailLaunch(ticketIds, jobId) {
+        if (!this.isActive())
+            return;
+        const ops = [];
+        const linkedIds = [];
+        for (const localId of ticketIds) {
+            const link = (0, jira_db_1.getLinkByLocalId)(this.db, localId);
+            if (!link || link.tombstoned)
+                continue;
+            linkedIds.push(localId);
+            ops.push({
+                jiraIssueId: link.jiraIssueId,
+                opType: 'transition',
+                idempotencyKey: `${jobId}:${localId}:transition:in_progress`,
+                payload: { localId, jiraIssueId: link.jiraIssueId, logicalState: 'in_progress' },
+            });
+        }
+        if (ops.length === 0)
+            return;
+        (0, jira_db_1.enqueueMany)(this.db, ops);
+        this.writeLocalStatus(linkedIds, 'in_progress');
+        this.broadcastOutboxState();
+    }
+    /**
+     * Called after a Jira-backed spec is edited + saved locally. Pushes the changed
+     * editable fields (summary/description/labels/priority) to the Jira issue via a
+     * durable 'update' op. No-op for non-Jira / unlinked specs. While the op is
+     * pending the id is frozen, so the inbound poll won't revert the local edit.
+     * Status is intentionally NOT written here (Jira status needs a transition).
+     */
+    onSpecEdited(localId, changes) {
+        if (!this.isActive())
+            return;
+        const link = (0, jira_db_1.getLinkByLocalId)(this.db, localId);
+        if (!link || link.tombstoned)
+            return;
+        const conn = (0, jira_db_1.getConnection)(this.db, this.projectId);
+        if (!conn)
+            return;
+        const fields = {};
+        if (typeof changes.title === 'string' && changes.title.trim())
+            fields.summary = changes.title.trim().slice(0, 250);
+        if (typeof changes.description === 'string')
+            fields.description = (0, jira_adf_1.bodyForDeployment)(changes.description, conn.deployment);
+        if (changes.labels !== undefined)
+            fields.labels = (changes.labels ?? []).filter((l) => typeof l === 'string');
+        if (changes.priority) {
+            const name = PRIORITY_TO_JIRA[changes.priority];
+            if (name)
+                fields.priority = { name };
+        }
+        if (Object.keys(fields).length === 0)
+            return;
+        const nonce = Date.now().toString(36);
+        (0, jira_db_1.enqueueMany)(this.db, [
+            {
+                jiraIssueId: link.jiraIssueId,
+                opType: 'update',
+                idempotencyKey: `update:${localId}:${nonce}`,
+                payload: { jiraIssueId: link.jiraIssueId, fields },
+            },
+        ]);
+        this.broadcastOutboxState();
+        void this.drainOnce().catch(() => undefined);
+    }
+    /**
+     * Called from project-registry's onJobFinished AFTER the local cache mutation.
+     * Enqueues the Jira status transition + completion comment per linked ticket.
+     */
+    onJobOutcome(args) {
+        if (!this.isActive())
+            return;
+        const needsReview = new Set(args.needsReviewIds ?? []);
+        const ops = [];
+        for (const localId of args.ticketIds) {
+            const link = (0, jira_db_1.getLinkByLocalId)(this.db, localId);
+            if (!link || link.tombstoned)
+                continue;
+            const reviewing = needsReview.has(localId);
+            // Completion comment (always safe/additive). Marker makes it idempotent.
+            const commentText = buildCompletionComment(args, link.jiraKey, reviewing);
+            ops.push({
+                jiraIssueId: link.jiraIssueId,
+                opType: 'comment',
+                idempotencyKey: `${args.jobId}:${localId}:comment`,
+                payload: { jiraIssueId: link.jiraIssueId, text: commentText, marker: (0, jira_adf_1.commentMarker)(args.jobId, localId) },
+            });
+            // Status transition: success → done (unless needs_review); else revert → todo.
+            // needs_review keeps status unchanged in Jira (no equivalent) — comment only.
+            if (reviewing)
+                continue;
+            const logicalState = args.status === 'completed' ? 'done' : 'todo';
+            ops.push({
+                jiraIssueId: link.jiraIssueId,
+                opType: 'transition',
+                idempotencyKey: `${args.jobId}:${localId}:transition:${logicalState}`,
+                payload: { localId, jiraIssueId: link.jiraIssueId, logicalState },
+            });
+        }
+        if (ops.length === 0)
+            return;
+        (0, jira_db_1.enqueueMany)(this.db, ops);
+        this.broadcastOutboxState();
+        // Drain promptly (best-effort) so PMs see the update without waiting a tick.
+        void this.drainOnce().catch(() => undefined);
+    }
+    /**
+     * "Discard" a Jira-backed spec: instead of a destructive local delete, move the
+     * linked issue to the user-configured discard status and (optionally) post a
+     * reason comment. The local cache is optimistically flipped to `cancelled` so
+     * the spec leaves the active board immediately; the inbound poll later
+     * reconciles it to the issue's real status (protected meanwhile by the
+     * pending-transition frozen guard).
+     */
+    discardSpec(localId, comment) {
+        if (!this.isActive())
+            return { ok: false, reason: 'not-active' };
+        const link = (0, jira_db_1.getLinkByLocalId)(this.db, localId);
+        if (!link || link.tombstoned)
+            return { ok: false, reason: 'no-link' };
+        const conn = (0, jira_db_1.getConnection)(this.db, this.projectId);
+        const target = conn?.discardStatus ?? null;
+        if (!target)
+            return { ok: false, reason: 'not-configured' };
+        // Distinct per-action nonce so a re-discard isn't deduped by idempotency key.
+        const nonce = Date.now().toString(36);
+        const ops = [];
+        const trimmed = (comment ?? '').trim();
+        if (trimmed) {
+            ops.push({
+                jiraIssueId: link.jiraIssueId,
+                opType: 'comment',
+                idempotencyKey: `discard:${localId}:${nonce}:comment`,
+                payload: { jiraIssueId: link.jiraIssueId, text: trimmed, marker: (0, jira_adf_1.discardCommentMarker)(localId, nonce) },
+            });
+        }
+        ops.push({
+            jiraIssueId: link.jiraIssueId,
+            opType: 'transition',
+            idempotencyKey: `discard:${localId}:${nonce}:transition`,
+            payload: { localId, jiraIssueId: link.jiraIssueId, logicalState: 'cancelled', targetStatus: target },
+        });
+        (0, jira_db_1.enqueueMany)(this.db, ops);
+        this.writeLocalStatus([localId], 'cancelled');
+        this.broadcastOutboxState();
+        void this.drainOnce().catch(() => undefined);
+        return { ok: true };
+    }
+    // ─── Outbox drain ──────────────────────────────────────────────────────────
+    async drainOnce() {
+        if (this.authPaused)
+            return;
+        const conn = (0, jira_db_1.getConnection)(this.db, this.projectId);
+        if (!conn || !conn.enabled)
+            return;
+        const client = this.buildClient();
+        if (!client)
+            return;
+        const batch = (0, jira_db_1.claimDrainable)(this.db, MAX_DRAIN_BATCH);
+        if (batch.length === 0)
+            return;
+        await Promise.all(batch.map((op) => this.executeOp(client, conn, op)));
+        this.broadcastOutboxState();
+    }
+    async executeOp(client, conn, op) {
+        try {
+            const payload = JSON.parse(op.payload);
+            if (op.opType === 'comment') {
+                await this.executeComment(client, op, payload);
+            }
+            else if (op.opType === 'transition') {
+                await this.executeTransition(client, conn, op, payload);
+            }
+            else if (op.opType === 'update') {
+                await this.executeUpdate(client, op, payload);
+            }
+            else {
+                (0, jira_db_1.markOutboxDead)(this.db, op.id, `unsupported op type ${op.opType}`);
+            }
+        }
+        catch (err) {
+            this.retryOrDead(op, err instanceof Error ? err.message : String(err));
+        }
+    }
+    async executeUpdate(client, op, payload) {
+        let res = await client.updateIssue(payload.jiraIssueId, payload.fields);
+        // The priority NAME may not match the instance's scheme. Don't let that lose
+        // the title/description/labels edit — retry once without priority.
+        if (!res.ok && res.code === 'validation' && 'priority' in payload.fields) {
+            const { priority: _drop, ...rest } = payload.fields;
+            void _drop;
+            if (Object.keys(rest).length > 0)
+                res = await client.updateIssue(payload.jiraIssueId, rest);
+        }
+        if (res.ok) {
+            (0, jira_db_1.markOutboxDone)(this.db, op.id);
+            return;
+        }
+        if (res.code === 'not_found') {
+            (0, jira_db_1.tombstoneLink)(this.db, payload.jiraIssueId);
+            (0, jira_db_1.markOutboxDead)(this.db, op.id, 'issue deleted or inaccessible');
+            this.broadcastDegraded(null, 'linked Jira issue no longer reachable');
+            return;
+        }
+        this.handleHardError(op, res.code, res.status, res.retryAfterMs, res.error);
+    }
+    async executeComment(client, op, payload) {
+        // Idempotency: skip if a comment already carries this op's marker (stored as
+        // an invisible comment property, with a legacy body-scan fallback).
+        const existing = await client.getComments(payload.jiraIssueId);
+        if (existing.ok) {
+            const dup = existing.data.comments.some((c) => (0, jira_adf_1.commentHasMarker)(c, payload.marker));
+            if (dup) {
+                (0, jira_db_1.markOutboxDone)(this.db, op.id);
+                return;
+            }
+        }
+        else if (this.handleHardError(op, existing.code, existing.status, existing.retryAfterMs, existing.error)) {
+            return;
+        }
+        // Post the user-facing text only; the marker rides along as a hidden
+        // comment property so it never appears in the rendered comment.
+        const res = await client.addComment(payload.jiraIssueId, payload.text, payload.marker);
+        if (res.ok) {
+            (0, jira_db_1.markOutboxDone)(this.db, op.id);
+            return;
+        }
+        this.handleHardError(op, res.code, res.status, res.retryAfterMs, res.error);
+    }
+    async executeTransition(client, conn, op, payload) {
+        // Re-GET the live issue for idempotency-first: skip if already in target category.
+        const issue = await client.getIssue(payload.jiraIssueId, ['status']);
+        if (!issue.ok) {
+            if (issue.code === 'not_found') {
+                (0, jira_db_1.tombstoneLink)(this.db, payload.jiraIssueId);
+                (0, jira_db_1.markOutboxDead)(this.db, op.id, 'issue deleted or inaccessible');
+                this.broadcastDegraded(null, 'linked Jira issue no longer reachable');
+                return;
+            }
+            if (this.handleHardError(op, issue.code, issue.status, issue.retryAfterMs, issue.error))
+                return;
+            this.retryOrDead(op, issue.error);
+            return;
+        }
+        const currentCategory = issue.data.fields.status?.statusCategory?.key ?? 'indeterminate';
+        // A per-op explicit target (e.g. the discard "move-to" status) wins over the
+        // connection's per-logical-state status map.
+        const explicitTarget = payload.targetStatus ?? conn.statusMap?.[payload.logicalState];
+        const outcome = await (0, jira_status_resolver_1.walkToCategory)({
+            state: payload.logicalState,
+            currentCategory,
+            explicitTarget,
+            getTransitions: async () => {
+                const res = await client.getTransitions(payload.jiraIssueId);
+                if (!res.ok)
+                    throw new JiraOpError(res.code, res.status, res.retryAfterMs, res.error);
+                return res.data.transitions;
+            },
+            applyTransition: async (transition) => {
+                const plan = (0, jira_status_resolver_1.buildTransitionFields)(transition, payload.logicalState);
+                const res = await client.transitionIssue(payload.jiraIssueId, transition.id, plan.fields);
+                if (!res.ok)
+                    throw new JiraOpError(res.code, res.status, res.retryAfterMs, res.error);
+            },
+        });
+        switch (outcome.status) {
+            case 'noop':
+            case 'applied':
+                (0, jira_db_1.markOutboxDone)(this.db, op.id);
+                return;
+            case 'no_path':
+            case 'blocked':
+                (0, jira_db_1.markOutboxDead)(this.db, op.id, outcome.reason);
+                this.broadcastDegraded(null, `status not synced — ${outcome.reason}; manual move may be needed`);
+                return;
+            case 'error':
+                this.retryOrDead(op, outcome.reason);
+                return;
+        }
+    }
+    /**
+     * Centralised hard-error handling. Returns true when the error was terminal
+     * (op finished/parked/dead) and the caller must stop.
+     */
+    handleHardError(op, code, status, retryAfterMs, error) {
+        if (code === 'auth') {
+            this.onAuth401();
+            // Park the op back to pending so it replays after re-auth.
+            (0, jira_db_1.markOutboxRetry)(this.db, op.id, new Date(Date.now() + 60_000).toISOString(), 'auth: token expired/revoked');
+            return true;
+        }
+        if (code === 'permission') {
+            (0, jira_db_1.markOutboxDead)(this.db, op.id, `permission denied (403): ${error}`);
+            this.broadcastDegraded(null, 'your Jira account cannot perform this operation');
+            return true;
+        }
+        if (code === 'not_found') {
+            (0, jira_db_1.tombstoneLink)(this.db, op.jiraIssueId);
+            (0, jira_db_1.markOutboxDead)(this.db, op.id, 'issue deleted or inaccessible');
+            return true;
+        }
+        if (code === 'validation' || code === 'no_transition') {
+            (0, jira_db_1.markOutboxDead)(this.db, op.id, `validation error: ${error}`);
+            return true;
+        }
+        if (code === 'rate_limit') {
+            const delay = retryAfterMs ?? backoffMs(op.attempts);
+            (0, jira_db_1.markOutboxRetry)(this.db, op.id, new Date(Date.now() + delay).toISOString(), `rate limited (429)`);
+            return true;
+        }
+        // server / network → retry with backoff
+        this.retryOrDead(op, error);
+        return true;
+    }
+    retryOrDead(op, error) {
+        if (error.startsWith('JiraOpError:')) {
+            // Unwrap a thrown JiraOpError to classify it.
+            const parsed = JiraOpError.parse(error);
+            if (parsed) {
+                this.handleHardError(op, parsed.code, parsed.status, parsed.retryAfterMs, parsed.message);
+                return;
+            }
+        }
+        const MAX_ATTEMPTS = 6;
+        if (op.attempts + 1 >= MAX_ATTEMPTS) {
+            (0, jira_db_1.markOutboxDead)(this.db, op.id, `exhausted retries: ${error}`);
+            return;
+        }
+        (0, jira_db_1.markOutboxRetry)(this.db, op.id, new Date(Date.now() + backoffMs(op.attempts)).toISOString(), error);
+    }
+    onAuth401() {
+        this.authPaused = true;
+        const pending = (0, jira_db_1.listOutbox)(this.db, { state: 'pending' }).length + (0, jira_db_1.listOutbox)(this.db, { state: 'inflight' }).length;
+        this.broadcast({ type: 'jira.auth_expired', projectId: this.projectId, pending });
+    }
+    /** Re-paste of a fresh token clears the auth-pause and drains the parked outbox. */
+    resumeAfterReauth() {
+        this.authPaused = false;
+        void this.drainOnce().catch(() => undefined);
+    }
+    // ─── Local cache helpers ───────────────────────────────────────────────────
+    writeLocalStatus(localIds, status) {
+        if (localIds.length === 0)
+            return;
+        try {
+            const file = (0, ticket_store_1.resolveTicketStoragePath)(this.projectPath);
+            const ids = new Set(localIds.map(String));
+            const now = new Date().toISOString();
+            const store = (0, ticket_store_1.mutateStore)(file, (s) => {
+                for (const id of ids) {
+                    const t = s.tickets[id];
+                    if (t && t.status !== status) {
+                        t.status = status;
+                        t.updated_at = now;
+                    }
+                }
+            });
+            this.notifyLocalWrite(store.revision);
+            for (const id of ids) {
+                const t = store.tickets[id];
+                if (t)
+                    this.broadcast({ type: 'ticket_updated', ticket: t, projectId: this.projectId, timestamp: t.updated_at });
+            }
+        }
+        catch (err) {
+            console.error('[jira-sync] writeLocalStatus failed:', err);
+        }
+    }
+    broadcastOutboxState() {
+        const counts = (0, jira_db_1.countOutboxByState)(this.db);
+        this.broadcast({ type: 'jira.outbox_changed', projectId: this.projectId, pending: counts.pending + counts.inflight, dead: counts.dead });
+    }
+    broadcastDegraded(jiraKey, reason) {
+        this.broadcast({ type: 'jira.degraded', projectId: this.projectId, jiraKey, reason });
+    }
+    // ─── Read-only details panel (issue fields + Development) ───────────────────
+    /**
+     * Build the read-only "Jira details" + "Development" payload for a Jira-backed
+     * spec. Resilient: the issue fetch is load-bearing, but a /field or dev-status
+     * failure still returns the fields (with humanized labels / empty development).
+     */
+    async getSpecDetails(localId) {
+        if (!this.isActive())
+            return { ok: false, reason: 'not-active' };
+        const link = (0, jira_db_1.getLinkByLocalId)(this.db, localId);
+        if (!link || link.tombstoned)
+            return { ok: false, reason: 'no-link' };
+        const conn = (0, jira_db_1.getConnection)(this.db, this.projectId);
+        const client = this.buildClient();
+        if (!conn || !client)
+            return { ok: false, reason: 'not-active' };
+        // 1) Fields — load-bearing.
+        const issueRes = await client.getIssueRaw(link.jiraIssueId);
+        if (!issueRes.ok) {
+            if (issueRes.code === 'auth')
+                this.onAuth401();
+            if (issueRes.code === 'not_found')
+                (0, jira_db_1.tombstoneLink)(this.db, link.jiraIssueId);
+            return { ok: false, reason: 'issue-error', status: issueRes.status };
+        }
+        // 2) /field metadata — best effort.
+        const metaRes = await client.getFieldsFull();
+        const fieldMeta = metaRes.ok ? metaRes.data : [];
+        // 3) Materialized ticket flags suppress already-shown info (no extra HTTP).
+        const ticket = (0, ticket_store_1.readStore)((0, ticket_store_1.resolveTicketStoragePath)(this.projectPath)).tickets[String(localId)];
+        const fields = (0, jira_issue_fields_1.formatIssueFields)({
+            fields: issueRes.data.fields,
+            fieldMeta,
+            baseUrl: conn.baseUrl,
+            alreadyShown: { hasEpicKey: !!ticket?.jira_epic_key, hasSprintName: !!ticket?.jira_sprint_name },
+        });
+        // 4) Development — best effort, fully isolated.
+        const development = await this.fetchDevelopment(client, link.jiraIssueId).catch(() => ({
+            pullRequests: [],
+            branches: [],
+            commits: [],
+        }));
+        return { ok: true, details: { fields, development } };
+    }
+    /** Two-call dev-status fetch (summary → detail per applicationType). Never throws. */
+    async fetchDevelopment(client, issueId) {
+        const empty = { pullRequests: [], branches: [], commits: [] };
+        const summary = await client.getDevStatusSummary(issueId);
+        if (!summary.ok) {
+            if (summary.code === 'auth')
+                this.onAuth401();
+            return empty;
+        }
+        const appTypesFor = (key) => Object.keys(summary.data.summary?.[key]?.byInstanceType ?? {});
+        const development = { pullRequests: [], branches: [], commits: [] };
+        const collect = async (key, dataType, sink) => {
+            for (const app of appTypesFor(key)) {
+                const res = await client.getDevStatusDetail(issueId, app, dataType);
+                if (res.ok)
+                    sink(res.data);
+            }
+        };
+        await collect('pullrequest', 'pullrequest', (d) => development.pullRequests.push(...(0, jira_issue_fields_1.normalizePullRequests)(d)));
+        await collect('branch', 'branch', (d) => development.branches.push(...(0, jira_issue_fields_1.normalizeBranches)(d)));
+        await collect('repository', 'repository', (d) => development.commits.push(...(0, jira_issue_fields_1.normalizeRepositoryCommits)(d)));
+        return development;
+    }
+    // ─── Read helpers for the router ───────────────────────────────────────────
+    listLinks() {
+        return (0, jira_db_1.listLinks)(this.db);
+    }
+    listOutbox(state) {
+        return (0, jira_db_1.listOutbox)(this.db, state ? { state } : {});
+    }
+    outboxCounts() {
+        return (0, jira_db_1.countOutboxByState)(this.db);
+    }
+}
+exports.JiraSyncManager = JiraSyncManager;
+// ─── Error envelope for thrown client failures inside the walk ─────────────────
+class JiraOpError extends Error {
+    code;
+    status;
+    retryAfterMs;
+    constructor(code, status, retryAfterMs, message) {
+        super(`JiraOpError:${code}:${status}:${retryAfterMs ?? ''}:${message}`);
+        this.code = code;
+        this.status = status;
+        this.retryAfterMs = retryAfterMs;
+    }
+    static parse(msg) {
+        if (!msg.startsWith('JiraOpError:'))
+            return null;
+        const rest = msg.slice('JiraOpError:'.length);
+        const [code, statusStr, retryStr, ...msgParts] = rest.split(':');
+        return {
+            code,
+            status: parseInt(statusStr, 10) || 0,
+            retryAfterMs: retryStr ? parseInt(retryStr, 10) : undefined,
+            message: msgParts.join(':'),
+        };
+    }
+}
+// ─── Pure helpers ──────────────────────────────────────────────────────────────
+function backoffMs(attempts) {
+    const base = Math.min(30_000, 2000 * 2 ** attempts);
+    const jitter = (attempts * 137) % 1000; // deterministic jitter (no Math.random)
+    return base + jitter;
+}
+/** Format an epoch-ms as Jira JQL date `"yyyy-MM-dd HH:mm"` (UTC). */
+function formatJqlDate(ms) {
+    const d = new Date(Math.max(0, ms));
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())} ${p(d.getUTCHours())}:${p(d.getUTCMinutes())}`;
+}
+function buildCompletionComment(args, jiraKey, needsReview) {
+    if (needsReview) {
+        return 'Specrails: the implementation rail terminated abnormally after its Ship phase — the result needs review.';
+    }
+    const parts = [];
+    if (args.status === 'completed') {
+        parts.push('✅ Implementation completed by a Specrails rail.');
+    }
+    else if (args.status === 'canceled') {
+        parts.push('⏹️ The Specrails implementation rail was cancelled — the spec was returned to the backlog.');
+    }
+    else {
+        parts.push('❌ The Specrails implementation rail failed — the spec was returned to the backlog.');
+    }
+    const meta = [`job ${args.jobId}`];
+    if (args.costUsd != null)
+        meta.push(`cost $${args.costUsd.toFixed(2)}`);
+    if (args.durationMs != null)
+        meta.push(`duration ${formatDuration(args.durationMs)}`);
+    parts.push(`(${meta.join(' · ')})`);
+    return parts.join('\n');
+}
+function formatDuration(ms) {
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    const rem = s % 60;
+    return rem ? `${m}m ${rem}s` : `${m}m`;
+}
+// Read a single ticket back from the store for a ticket_updated broadcast.
+function readTicket(projectPath, localId) {
+    try {
+        const store = (0, ticket_store_1.readStore)((0, ticket_store_1.resolveTicketStoragePath)(projectPath));
+        const t = store.tickets[String(localId)];
+        return t ?? null;
+    }
+    catch {
+        return null;
+    }
+}