agent-dealer 1.2.13 → 1.2.14

package/bundle/server/dist/routes/issues-source-attachments.test.js

@@ -0,0 +1,411 @@
+// NOT-364: atomic Linear attachment import and reload reconciliation.
+import { test, before, after, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import Fastify from "fastify";
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-issue-src-att-"));
+const { migrate, getDb } = await import("../db/index.js");
+const { BUILTIN_AGENT_CLAUDE_ID, BUILTIN_AGENT_CURSOR_ID } = await import("@agent-dealer/shared");
+const { registerIssueRoutes } = await import("./issues.js");
+const { listSourceAttachments } = await import("../repository/source-attachments.js");
+const { listQueuedEntries } = await import("../repository/queue-entries.js");
+const { listIssues } = await import("../repository/issues.js");
+const FILE_URL = "https://uploads.linear.app/abc/repro.tar.gz";
+const LINK_URL = "https://docs.example.com/spec";
+const TARBALL_V1 = Buffer.from("repro-tarball-version-one-bytes");
+const TARBALL_V2 = Buffer.from("repro-tarball-version-two-bytes!!");
+/** Current download bytes per URL; flip to simulate expiry/removal. */
+const downloadBytes = new Map();
+/** Linear issue node answered to GraphQL (reload path). */
+let linearNode = null;
+const realFetch = globalThis.fetch;
+before(() => {
+    migrate();
+    process.env.LINEAR_API_KEY = "test-key";
+    globalThis.fetch = (async (url, init) => {
+        const target = String(url);
+        if (target.includes("api.linear.app")) {
+            // Single-issue fetch answers the reload; relation walks (admission
+            // blocker checks behind the queue wait reason) answer no blockers.
+            const body = JSON.parse(String(init?.body ?? "{}"));
+            const payload = typeof body.variables?.id === "string"
+                ? { data: { issue: linearNode } }
+                : { data: { issues: { nodes: [], pageInfo: { hasNextPage: false, endCursor: null } } } };
+            return new Response(JSON.stringify(payload), {
+                status: 200,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        const fixture = downloadBytes.get(target);
+        if (fixture === "http500" || fixture === undefined) {
+            return new Response("boom", { status: 500 });
+        }
+        return new Response(new Uint8Array(fixture), {
+            status: 200,
+            headers: { "Content-Type": "application/gzip", "Content-Length": String(fixture.byteLength) },
+        });
+    });
+});
+after(() => {
+    globalThis.fetch = realFetch;
+    delete process.env.LINEAR_API_KEY;
+});
+beforeEach(() => {
+    downloadBytes.clear();
+    linearNode = null;
+    getDb().exec(`
+    DELETE FROM issue_source_attachments;
+    DELETE FROM work_items;
+    DELETE FROM human_actions;
+    DELETE FROM workflow_events;
+    DELETE FROM worker_sessions;
+    DELETE FROM artifacts;
+    DELETE FROM workflow_instances;
+    DELETE FROM queue_entries;
+    DELETE FROM issues;
+  `);
+});
+async function buildApp() {
+    const app = Fastify();
+    await registerIssueRoutes(app);
+    return app;
+}
+const BASE_LINEAR = {
+    title: "NOT-1: import me",
+    description: "Do the thing.",
+    repo: "acme/app",
+    baseBranch: "main",
+    developerAgentId: BUILTIN_AGENT_CLAUDE_ID,
+    reviewerAgentId: BUILTIN_AGENT_CURSOR_ID,
+    source: "linear",
+    externalId: "linear-uuid-1",
+    externalLabel: "NOT-1",
+    externalUrl: "https://linear.app/not-so-fat/issue/NOT-1/x",
+};
+const FILE_ATT = { id: "att-file-1", title: "repro.tar.gz", url: FILE_URL };
+const LINK_ATT = { id: "att-link-1", title: "Design doc", url: LINK_URL, subtitle: "Spec" };
+test("import snapshots a hosted .tar.gz and keeps the link as metadata", async () => {
+    downloadBytes.set(FILE_URL, TARBALL_V1);
+    const app = await buildApp();
+    const res = await app.inject({
+        method: "POST",
+        url: "/api/issues",
+        payload: { ...BASE_LINEAR, linearAttachments: [FILE_ATT, LINK_ATT] },
+    });
+    assert.equal(res.statusCode, 200, res.body);
+    const created = res.json();
+    assert.equal(res.json() && res.json().queue, "enqueued");
+    const rows = listSourceAttachments(created.id);
+    assert.equal(rows.length, 2);
+    const file = rows.find((r) => r.kind === "file");
+    assert.equal(file.linearAttachmentId, "att-file-1");
+    assert.equal(file.safeFileName, "repro.tar.gz");
+    assert.equal(file.sizeBytes, TARBALL_V1.byteLength);
+    assert.equal(file.sha256, createHash("sha256").update(TARBALL_V1).digest("hex"));
+    assert.ok(file.blobPath && fs.existsSync(file.blobPath));
+    assert.deepEqual(fs.readFileSync(file.blobPath), TARBALL_V1);
+    const link = rows.find((r) => r.kind === "link");
+    assert.equal(link.url, LINK_URL);
+    assert.equal(link.blobPath, undefined);
+    // The detail carries the same manifest for the Source attachments summary.
+    const detail = await app.inject({ method: "GET", url: `/api/issues/${created.id}` });
+    assert.equal(detail.statusCode, 200);
+    const body = detail.json();
+    assert.equal(body.sourceAttachments.length, 2);
+    await app.close();
+});
+test("import fails atomically when a hosted file download fails", async () => {
+    downloadBytes.set(FILE_URL, "http500");
+    const app = await buildApp();
+    const res = await app.inject({
+        method: "POST",
+        url: "/api/issues",
+        payload: { ...BASE_LINEAR, linearAttachments: [FILE_ATT, LINK_ATT] },
+    });
+    assert.equal(res.statusCode, 502, res.body);
+    assert.match(res.json().error, /HTTP 500/);
+    // Zero partial state: no issue, no queue entry, no attachment rows.
+    assert.equal(listIssues().length, 0);
+    assert.equal(listQueuedEntries().length, 0);
+    assert.equal(getDb().prepare("SELECT COUNT(*) AS n FROM issue_source_attachments").get().n, 0);
+    await app.close();
+});
+test("import refuses an oversized hosted file with zero rows", async () => {
+    const app = await buildApp();
+    const huge = { id: "att-big", title: "huge.bin", url: "https://uploads.linear.app/abc/huge.bin" };
+    downloadBytes.set(huge.url, Buffer.from("small-body"));
+    // Lie about the size the way an over-limit Linear upload would declare it.
+    const realMock = globalThis.fetch;
+    globalThis.fetch = (async (url, init) => {
+        if (String(url).includes("api.linear.app")) {
+            const parsed = JSON.parse(String(init?.body ?? "{}"));
+            const payload = typeof parsed.variables?.id === "string"
+                ? { data: { issue: null } }
+                : { data: { issues: { nodes: [], pageInfo: { hasNextPage: false, endCursor: null } } } };
+            return new Response(JSON.stringify(payload), { status: 200 });
+        }
+        return new Response(new Uint8Array(Buffer.from("small-body")), {
+            status: 200,
+            headers: { "Content-Type": "application/octet-stream", "Content-Length": String(300 * 1024 * 1024) },
+        });
+    });
+    try {
+        const res = await app.inject({
+            method: "POST",
+            url: "/api/issues",
+            payload: { ...BASE_LINEAR, linearAttachments: [huge] },
+        });
+        assert.equal(res.statusCode, 400, res.body);
+        assert.match(res.json().error, /too large to snapshot/);
+        assert.equal(listIssues().length, 0);
+        assert.equal(getDb().prepare("SELECT COUNT(*) AS n FROM issue_source_attachments").get().n, 0);
+    }
+    finally {
+        globalThis.fetch = realMock;
+    }
+    await app.close();
+});
+test("link-only import stores metadata without fetching", async () => {
+    let downloads = 0;
+    const realMock = globalThis.fetch;
+    globalThis.fetch = (async (url, init) => {
+        if (String(url).includes("api.linear.app")) {
+            const parsed = JSON.parse(String(init?.body ?? "{}"));
+            const payload = typeof parsed.variables?.id === "string"
+                ? { data: { issue: null } }
+                : { data: { issues: { nodes: [], pageInfo: { hasNextPage: false, endCursor: null } } } };
+            return new Response(JSON.stringify(payload), { status: 200 });
+        }
+        downloads += 1;
+        return new Response("nope", { status: 500 });
+    });
+    try {
+        const app = await buildApp();
+        const res = await app.inject({
+            method: "POST",
+            url: "/api/issues",
+            payload: { ...BASE_LINEAR, linearAttachments: [LINK_ATT] },
+        });
+        assert.equal(res.statusCode, 200, res.body);
+        const rows = listSourceAttachments(res.json().id);
+        assert.equal(rows.length, 1);
+        assert.equal(rows[0].kind, "link");
+        assert.equal(downloads, 0, "external-link targets are never fetched");
+        await app.close();
+    }
+    finally {
+        globalThis.fetch = realMock;
+    }
+});
+function linearNodeWith(attachments) {
+    return {
+        id: "linear-uuid-1",
+        identifier: "NOT-1",
+        title: "Reloaded title",
+        description: "Do the thing, reloaded.",
+        url: "https://linear.app/not-so-fat/issue/NOT-1/x",
+        state: { name: "Todo" },
+        team: { id: "team-1" },
+        labels: { nodes: [] },
+        attachments: { nodes: attachments },
+    };
+}
+test("reload reconciles added, changed, and removed attachments atomically", async () => {
+    downloadBytes.set(FILE_URL, TARBALL_V1);
+    const app = await buildApp();
+    const created = (await (await app.inject({
+        method: "POST",
+        url: "/api/issues",
+        payload: { ...BASE_LINEAR, linearAttachments: [FILE_ATT, LINK_ATT] },
+    })).json());
+    const beforeRows = listSourceAttachments(created.id);
+    const oldBlob = beforeRows.find((r) => r.kind === "file").blobPath;
+    assert.ok(fs.existsSync(oldBlob));
+    // Linear now: same file id with new bytes, link kept, second file removed
+    // (it is simply absent), brand-new file added.
+    const FILE_B_URL = "https://uploads.linear.app/abc/b.bin";
+    downloadBytes.set(FILE_URL, TARBALL_V2);
+    downloadBytes.set(FILE_B_URL, Buffer.from("brand-new-bytes"));
+    linearNode = linearNodeWith([
+        { id: "att-file-1", title: "repro.tar.gz", url: FILE_URL },
+        { id: "att-link-1", title: "Design doc", url: LINK_URL, subtitle: "Spec" },
+        { id: "att-file-3", title: "b.bin", url: FILE_B_URL },
+    ]);
+    const res = await app.inject({ method: "POST", url: `/api/issues/${created.id}/reload-source` });
+    assert.equal(res.statusCode, 200, res.body);
+    const rows = listSourceAttachments(created.id);
+    assert.equal(rows.length, 3);
+    const changed = rows.find((r) => r.linearAttachmentId === "att-file-1");
+    assert.equal(changed.sha256, createHash("sha256").update(TARBALL_V2).digest("hex"));
+    assert.deepEqual(fs.readFileSync(changed.blobPath), TARBALL_V2);
+    assert.ok(rows.some((r) => r.linearAttachmentId === "att-file-3"));
+    // Removed files disappear from the pre-execution snapshot. Blob paths are
+    // content-addressed, so the changed file lands on a new path with the new
+    // bytes and the old blob is pruned.
+    assert.deepEqual(fs.readFileSync(changed.blobPath), TARBALL_V2);
+    assert.ok(!rows.some((r) => r.linearAttachmentId === "att-file-2"));
+    assert.notEqual(changed.blobPath, oldBlob);
+    assert.ok(!fs.existsSync(oldBlob));
+    await app.close();
+});
+test("the frozen manifest survives later row changes; legacy snapshots read empty", async () => {
+    const { createIssue } = await import("../repository/issues.js");
+    const { createIssueArtifact } = await import("../repository/artifacts.js");
+    const { replaceSourceAttachments } = await import("../repository/source-attachments.js");
+    const { getTaskSnapshot, TASK_SNAPSHOT_ARTIFACT_KIND } = await import("../coordinator/commands.js");
+    const issue = createIssue({
+        title: "Frozen",
+        repo: "acme/app",
+        baseBranch: "main",
+        developerAgentId: BUILTIN_AGENT_CLAUDE_ID,
+        reviewerAgentId: BUILTIN_AGENT_CURSOR_ID,
+    });
+    const frozen = [
+        {
+            linearAttachmentId: "att-old",
+            kind: "file",
+            title: "old.bin",
+            safeFileName: "old.bin",
+            blobPath: "/blobs/old.bin",
+            sizeBytes: 3,
+            sha256: "aa",
+            url: "https://uploads.linear.app/old",
+        },
+    ];
+    replaceSourceAttachments(issue.id, frozen);
+    createIssueArtifact({
+        issueId: issue.id,
+        kind: TASK_SNAPSHOT_ARTIFACT_KIND,
+        author: "system",
+        content: {
+            title: issue.title,
+            description: "",
+            acceptanceCriteria: "",
+            repo: issue.repo,
+            baseBranch: issue.baseBranch,
+            workflowVersion: "dev_reviewer_v1",
+            executionContract: null,
+            sourceAttachments: frozen,
+        },
+    });
+    // A later Linear change swaps the live rows — the frozen read is unaffected.
+    replaceSourceAttachments(issue.id, [
+        {
+            linearAttachmentId: "att-new",
+            kind: "link",
+            title: "New",
+            url: "https://docs.example.com/new",
+        },
+    ]);
+    const { getIssue } = await import("../repository/issues.js");
+    assert.deepEqual(getTaskSnapshot(getIssue(issue.id)).sourceAttachments, frozen);
+    // Legacy snapshots (frozen before attachments) never gain inputs mid-flight.
+    const legacy = createIssue({
+        title: "Legacy",
+        repo: "acme/app",
+        baseBranch: "main",
+        developerAgentId: BUILTIN_AGENT_CLAUDE_ID,
+        reviewerAgentId: BUILTIN_AGENT_CURSOR_ID,
+    });
+    createIssueArtifact({
+        issueId: legacy.id,
+        kind: TASK_SNAPSHOT_ARTIFACT_KIND,
+        author: "system",
+        content: {
+            title: legacy.title,
+            description: "",
+            acceptanceCriteria: "",
+            repo: legacy.repo,
+            baseBranch: legacy.baseBranch,
+            workflowVersion: "dev_reviewer_v1",
+            executionContract: null,
+        },
+    });
+    replaceSourceAttachments(legacy.id, frozen);
+    assert.deepEqual(getTaskSnapshot(getIssue(legacy.id)).sourceAttachments, []);
+});
+test("reload race with admission (in-transaction 409) leaves prior blob bytes untouched", async () => {
+    downloadBytes.set(FILE_URL, TARBALL_V1);
+    const app = await buildApp();
+    const created = (await (await app.inject({
+        method: "POST",
+        url: "/api/issues",
+        payload: { ...BASE_LINEAR, linearAttachments: [FILE_ATT] },
+    })).json());
+    const beforeRows = listSourceAttachments(created.id);
+    assert.equal(beforeRows.length, 1);
+    const beforeBlobPath = beforeRows[0].blobPath;
+    const beforeHash = createHash("sha256").update(fs.readFileSync(beforeBlobPath)).digest("hex");
+    // The refreshed ticket carries changed bytes for the same attachment id.
+    downloadBytes.set(FILE_URL, TARBALL_V2);
+    const { reloadIssueSourceFromLinear } = await import("../coordinator/source-reload.js");
+    const { startWorkflowInstance } = await import("../repository/workflow-events.js");
+    const { getSourceAttachmentsDir } = await import("../paths.js");
+    const result = await reloadIssueSourceFromLinear(created.id, {
+        fetchLinearIssue: async (externalId) => {
+            // Admission wins the race mid-flight: by the time the write
+            // transaction runs, an active workflow owns the issue, so the
+            // in-transaction guard must answer 409 with no partial write.
+            startWorkflowInstance(created.id, "dev_reviewer_v1");
+            return {
+                id: externalId,
+                identifier: "NOT-1",
+                title: "Reloaded title",
+                description: "Do the thing, reloaded.",
+                url: "https://linear.app/not-so-fat/issue/NOT-1/x",
+                attachments: [{ id: "att-file-1", title: "repro.tar.gz", url: FILE_URL }],
+            };
+        },
+    });
+    if (result.ok)
+        assert.fail("expected the admission race to answer 409");
+    assert.equal(result.code, 409);
+    // Old task text and old attachment rows preserved — and, crucially, the
+    // old blob path still holds the old bytes (a pre-fix store overwrote the
+    // deterministic path before the transaction, breaking the frozen sha256).
+    const { getIssue } = await import("../repository/issues.js");
+    assert.equal(getIssue(created.id).title, BASE_LINEAR.title);
+    const afterRows = listSourceAttachments(created.id);
+    assert.deepEqual(afterRows.map((r) => r.linearAttachmentId), ["att-file-1"]);
+    assert.equal(afterRows[0].blobPath, beforeBlobPath);
+    assert.deepEqual(fs.readFileSync(afterRows[0].blobPath), TARBALL_V1);
+    assert.equal(createHash("sha256").update(fs.readFileSync(afterRows[0].blobPath)).digest("hex"), beforeHash);
+    // The staged-but-never-committed V2 bytes were pruned, not left behind.
+    assert.deepEqual(fs.readdirSync(path.join(getSourceAttachmentsDir(), created.id)), [
+        path.basename(beforeBlobPath),
+    ]);
+    await app.close();
+});
+test("failed reload preserves the old task text and attachment snapshot", async () => {
+    downloadBytes.set(FILE_URL, TARBALL_V1);
+    const app = await buildApp();
+    const created = (await (await app.inject({
+        method: "POST",
+        url: "/api/issues",
+        payload: { ...BASE_LINEAR, linearAttachments: [FILE_ATT] },
+    })).json());
+    const beforeRows = listSourceAttachments(created.id);
+    const beforeBlobHash = createHash("sha256")
+        .update(fs.readFileSync(beforeRows[0].blobPath))
+        .digest("hex");
+    // The refreshed ticket adds a file whose download fails.
+    const BAD_URL = "https://uploads.linear.app/abc/missing.bin";
+    downloadBytes.set(BAD_URL, "http500");
+    linearNode = linearNodeWith([
+        { id: "att-file-1", title: "repro.tar.gz", url: FILE_URL },
+        { id: "att-file-9", title: "missing.bin", url: BAD_URL },
+    ]);
+    const res = await app.inject({ method: "POST", url: `/api/issues/${created.id}/reload-source` });
+    assert.equal(res.statusCode, 502, res.body);
+    const { getIssue } = await import("../repository/issues.js");
+    const issue = getIssue(created.id);
+    assert.equal(issue.title, BASE_LINEAR.title, "old task text preserved");
+    assert.equal(issue.description, BASE_LINEAR.description);
+    const afterRows = listSourceAttachments(created.id);
+    assert.deepEqual(afterRows.map((r) => r.linearAttachmentId), ["att-file-1"], "old attachment snapshot preserved");
+    assert.equal(createHash("sha256").update(fs.readFileSync(afterRows[0].blobPath)).digest("hex"), beforeBlobHash, "old blob bytes intact");
+    await app.close();
+});

package/bundle/server/dist/routes/issues.js

@@ -1,5 +1,6 @@
 // packages/server/src/routes/issues.ts
 import fs from "node:fs";
+import path from "node:path";
 import { CreateIssueInput, ExecutionContractError, IssueStatus, UpdateIssueInput, } from "@agent-dealer/shared";
 import { getDb } from "../db/index.js";
 import { createIssue, getIssue, listIssues, findActiveIssueByExternalId, listIssuesByExternalId, queryIssues, updateIssue, listRecentRepos } from "../repository/issues.js";
@@ -16,6 +17,11 @@ import { computeHumanWaitMs } from "../coordinator/metrics.js";
 import { enqueueIssue, enqueueIssueWithOutcome, getQueuedEntryForIssue } from "../repository/queue-entries.js";
 import { latestSessionFailureForIssue } from "../coordinator/latest-failure.js";
 import { getIssueExecutionAnalysis } from "../read-models/execution-analysis.js";
+import { reloadIssueSourceFromLinear } from "../coordinator/source-reload.js";
+import { discardStaged, SourceAttachmentError, stageSourceAttachments, storeStagedAttachments, } from "../coordinator/source-attachments.js";
+import { listSourceAttachments, replaceSourceAttachments } from "../repository/source-attachments.js";
+import { getSourceAttachmentsDir } from "../paths.js";
+import { persistLinearBranchForIssue } from "../adapters/linear-inbox.js";
 import { deriveLiveProgressFromLog } from "../coordinator/session-progress.js";
 import { branchTipStatusForIssue } from "../coordinator/branch-tip-status.js";
 const TRACE_DEFAULT_MAX_CHARS = 50_000;
@@ -144,6 +150,9 @@ export async function registerIssueRoutes(app) {
             // NOT-358: usage-cap / deck-outage wait behind an availability window, if any —
             // the dashboard offers "Park for human" next to the wait notice.
             capWait: capWaitForIssue(id),
+            // NOT-364: durable Linear source attachments — files with safe name, size
+            // and checksum plus Dealer blob path; links as labeled metadata only.
+            sourceAttachments: listSourceAttachments(id),
         };
     });
     /** NOT-173: stable issue-level execution read model. The existing
@@ -226,18 +235,77 @@ export async function registerIssueRoutes(app) {
                 });
             }
         }
+        // NOT-364: snapshot Linear-hosted files BEFORE any row exists. The
+        // From-Linear form sends the lookup-time attachment metadata; every hosted
+        // file streams into the staging dir here, so an HTTP failure, timeout, or
+        // limit breach refuses the whole create with zero issue/queue/attachment
+        // rows. External links pass through as metadata (never downloaded).
+        // Non-Linear sources ignore the field; re-imports of a live issue return
+        // above and never re-download (use Reload from Linear pre-execution).
+        const snapshotAttachments = input.source === "linear" && (input.linearAttachments?.length ?? 0) > 0;
+        let staged = null;
+        if (snapshotAttachments) {
+            try {
+                staged = await stageSourceAttachments(input.linearAttachments ?? []);
+            }
+            catch (err) {
+                if (err instanceof SourceAttachmentError) {
+                    return reply.status(err.httpStatus).send({ error: err.message });
+                }
+                throw err;
+            }
+        }
         // NOT-306: an ambiguous/malformed execution contract in the ticket
         // description is a 400 with an actionable message, never a silent drop.
         let issue;
+        // The issue id minted inside the transaction, so a throw after the blob
+        // copy can remove the orphaned bytes (rows roll back; files do not).
+        let createdIssueId = null;
         try {
-            issue = createIssue(input);
+            // The issue row and its attachment rows commit in one transaction — a
+            // throw below the staging point (contract error, blob-store failure)
+            // rolls back to zero rows, never a partially hydrated issue.
+            issue = getDb().transaction(() => {
+                const created = createIssue(input);
+                createdIssueId = created.id;
+                if (staged) {
+                    replaceSourceAttachments(created.id, storeStagedAttachments(created.id, staged));
+                }
+                return created;
+            })();
         }
         catch (err) {
+            if (staged)
+                discardStaged(staged);
+            if (createdIssueId) {
+                try {
+                    const orphanDir = path.resolve(getSourceAttachmentsDir(), createdIssueId);
+                    if (orphanDir.startsWith(path.resolve(getSourceAttachmentsDir()) + path.sep)) {
+                        fs.rmSync(orphanDir, { recursive: true, force: true });
+                    }
+                }
+                catch {
+                    // orphan blobs are retained history, never a correctness issue
+                }
+            }
             if (err instanceof ExecutionContractError) {
                 return reply.status(400).send({ error: err.message });
             }
+            if (err instanceof SourceAttachmentError) {
+                return reply.status(err.httpStatus).send({ error: err.message });
+            }
             throw err;
         }
+        if (staged)
+            discardStaged(staged);
+        // NOT-362: seed the issue branch from Linear's own `branchName` (source
+        // `linear` only; manual issues untouched). Best-effort and awaited — the
+        // developer round reads the branch at admission, so it must be stored
+        // before the enqueue below. Never fails the import.
+        if (input.source === "linear" && input.externalId) {
+            await persistLinearBranchForIssue(issue.id).catch(() => null);
+            issue = getIssue(issue.id) ?? issue;
+        }
         appendWorkflowEvent({ issueId: issue.id, type: "issue.created", actorType: "human", stage: issue.status });
         // NOT-118: create enqueues, it never starts. Server-side so the UI, CLI and agents all
         // behave the same — callers hold no workflow logic. `enqueue: false` creates a draft.
@@ -381,6 +449,26 @@ export async function registerIssueRoutes(app) {
         await refreshQueueWaitReasonForIssue(id);
         return updated;
     });
+    /**
+     * NOT-363: reload a Linear-sourced issue's task text from its linked ticket.
+     * Only while `ready` with no active workflow or running worker — a race
+     * with admission fails closed with 409. Replaces title + description
+     * atomically, recompiles the execution contract, and swaps the acceptance
+     * criteria for the freshly derived ones; repo, agents, policy fields,
+     * auto-merge, queue position, and coordinator-owned fields are preserved.
+     * Queue order is untouched (the write never touches queue_entries) — the
+     * position is preserved by construction.
+     */
+    app.post("/api/issues/:id/reload-source", async (req, reply) => {
+        const { id } = req.params;
+        const result = await reloadIssueSourceFromLinear(id);
+        if (!result.ok)
+            return reply.status(result.code).send({ error: result.error });
+        // A queued issue keeps its position; re-derive the visible wait reason now
+        // that admission may see a different (e.g. healthy) description.
+        await refreshQueueWaitReasonForIssue(id);
+        return result.issue;
+    });
     /**
      * NOT-118: Start = move to front of the admission queue, then admit if a slot is free.
      * No bypass — a busy or not-yet-eligible issue answers `{ state: "queued", ... }` and is

package/bundle/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dealer/server",
-  "version": "1.2.13",
+  "version": "1.2.14",
   "type": "module",
   "main": "dist/index.js",
   "files": [
@@ -22,7 +22,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@agent-dealer/shared": "1.2.13",
+    "@agent-dealer/shared": "1.2.14",
     "@fastify/cors": "^11.0.1",
     "@fastify/static": "^8.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",