agent-dealer 1.2.13 → 1.2.15

package/bundle/server/dist/coordinator/source-attachments.test.js

@@ -0,0 +1,396 @@
+// NOT-364: Linear source-attachment staging, safe names, materialization, prompts.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createHash, randomBytes } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { LINEAR_INPUT_EXCLUDE_LINE, MAX_SOURCE_ATTACHMENT_FILE_BYTES, MAX_SOURCE_ATTACHMENT_TOTAL_BYTES, materializeSourceAttachments, safeAttachmentFileName, sourceAttachmentsDeveloperSection, sourceAttachmentsReviewerSection, stageSourceAttachments, storeStagedAttachments, discardStaged, SourceAttachmentError, } from "./source-attachments.js";
+const HOSTED = "https://uploads.linear.app/abc/repro.tar.gz";
+const LINK = "https://docs.example.com/spec";
+function downloadDouble(bytes, opts = {}) {
+    return async (url) => {
+        opts.seen?.push(url);
+        const headers = {
+            get: (name) => {
+                if (name === "content-type")
+                    return opts.contentType ?? "application/gzip";
+                if (name === "content-length")
+                    return String(bytes.byteLength);
+                return null;
+            },
+        };
+        if (opts.streamed === false) {
+            const exact = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+            return { ok: true, status: 200, headers, arrayBuffer: async () => exact };
+        }
+        const chunks = [bytes.subarray(0, 5), bytes.subarray(5)];
+        let i = 0;
+        return {
+            ok: true,
+            status: 200,
+            headers,
+            body: {
+                getReader: () => ({
+                    read: async () => {
+                        if (i >= chunks.length)
+                            return { done: true, value: undefined };
+                        const value = chunks[i++];
+                        return { done: false, value };
+                    },
+                    cancel: async () => { },
+                }),
+            },
+        };
+    };
+}
+const FILE_ATTACHMENT = { id: "att-file-1", title: "repro.tar.gz", url: HOSTED };
+const LINK_ATTACHMENT = {
+    id: "att-link-1",
+    title: "Design doc",
+    url: LINK,
+    subtitle: "Spec",
+    source: "google-docs",
+};
+test("staging snapshots exact bytes with sha256 and passes links through unfetched", async () => {
+    const bytes = Buffer.from("fake-tar-bytes-0123456789");
+    const seen = [];
+    const staged = await stageSourceAttachments([FILE_ATTACHMENT, LINK_ATTACHMENT], {
+        fetchImpl: downloadDouble(bytes, { seen }),
+    });
+    try {
+        assert.equal(staged.files.length, 1);
+        const [file] = staged.files;
+        assert.equal(file.safeFileName, "repro.tar.gz");
+        assert.equal(file.sizeBytes, bytes.byteLength);
+        assert.equal(file.sha256, createHash("sha256").update(bytes).digest("hex"));
+        assert.equal(file.contentType, "application/gzip");
+        assert.deepEqual(fs.readFileSync(file.tempPath), bytes);
+        // The external link is metadata only — its URL is never fetched.
+        assert.equal(staged.links.length, 1);
+        assert.equal(staged.links[0].kind, "link");
+        assert.equal(staged.links[0].url, LINK);
+        assert.deepEqual(seen, [HOSTED]);
+    }
+    finally {
+        discardStaged(staged);
+    }
+});
+test("staging refuses an HTTP failure without a partial bundle", async () => {
+    const fetchImpl = async () => ({
+        ok: false,
+        status: 500,
+        headers: { get: () => null },
+    });
+    await assert.rejects(() => stageSourceAttachments([FILE_ATTACHMENT], { fetchImpl }), (err) => {
+        assert.ok(err instanceof SourceAttachmentError);
+        assert.equal(err.httpStatus, 502);
+        assert.match(err.message, /HTTP 500/);
+        return true;
+    });
+});
+test("staging times out a hanging download", async () => {
+    const fetchImpl = (_url, init) => new Promise((_resolve, reject) => {
+        init?.signal?.addEventListener("abort", () => reject(new Error("aborted")));
+    });
+    await assert.rejects(() => stageSourceAttachments([FILE_ATTACHMENT], { fetchImpl, timeoutMs: 20 }), (err) => {
+        assert.ok(err instanceof SourceAttachmentError);
+        assert.equal(err.httpStatus, 502);
+        assert.match(err.message, /timed out/);
+        return true;
+    });
+});
+test("staging enforces the per-file and total snapshot limits", async () => {
+    const bytes = Buffer.from("0123456789abcdef");
+    await assert.rejects(() => stageSourceAttachments([FILE_ATTACHMENT], {
+        fetchImpl: downloadDouble(bytes),
+        maxFileBytes: 4,
+    }), (err) => {
+        assert.ok(err instanceof SourceAttachmentError);
+        assert.equal(err.httpStatus, 400);
+        assert.match(err.message, /too large to snapshot/);
+        return true;
+    });
+    const second = { id: "att-file-2", title: "b.bin", url: `${HOSTED}-b` };
+    await assert.rejects(() => stageSourceAttachments([FILE_ATTACHMENT, second], {
+        fetchImpl: downloadDouble(bytes),
+        maxTotalBytes: bytes.byteLength + 1,
+    }), (err) => {
+        assert.ok(err instanceof SourceAttachmentError);
+        assert.equal(err.httpStatus, 400);
+        assert.match(err.message, /total snapshot limit/);
+        return true;
+    });
+});
+test("staging fails fast on a declared over-limit body", async () => {
+    let read = false;
+    const fetchImpl = async () => ({
+        ok: true,
+        status: 200,
+        headers: {
+            get: (name) => (name === "content-length" ? String(MAX_SOURCE_ATTACHMENT_FILE_BYTES + 1) : "application/gzip"),
+        },
+        arrayBuffer: async () => {
+            read = true;
+            return new ArrayBuffer(0);
+        },
+    });
+    await assert.rejects(() => stageSourceAttachments([FILE_ATTACHMENT], { fetchImpl }), (err) => {
+        assert.ok(err instanceof SourceAttachmentError);
+        assert.equal(err.httpStatus, 400);
+        return true;
+    });
+    assert.equal(read, false, "over-limit body is refused before reading");
+});
+test("default snapshot limits are 100 MiB per file and 250 MiB total", () => {
+    assert.equal(MAX_SOURCE_ATTACHMENT_FILE_BYTES, 100 * 1024 * 1024);
+    assert.equal(MAX_SOURCE_ATTACHMENT_TOTAL_BYTES, 250 * 1024 * 1024);
+});
+test("safeAttachmentFileName neutralizes traversal and de-duplicates", () => {
+    const taken = new Set();
+    assert.equal(safeAttachmentFileName("../../etc/passwd", "att-1", taken), "passwd");
+    assert.equal(safeAttachmentFileName(".hidden", "att-2", taken), "_hidden");
+    assert.equal(safeAttachmentFileName("..", "abcdef12", taken), "attachment-abcdef12");
+    assert.equal(safeAttachmentFileName("repro.tar.gz", "x1", taken), "repro.tar.gz");
+    assert.equal(safeAttachmentFileName("repro.tar.gz", "x2", taken), "repro.tar-2.gz");
+    for (const name of taken) {
+        assert.ok(!name.includes("/") && !name.includes("\\"), name);
+    }
+});
+function initWorktree() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-inputs-worktree-"));
+    execFileSync("git", ["init", "-q"], { cwd: dir });
+    execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: dir });
+    execFileSync("git", ["config", "user.name", "test"], { cwd: dir });
+    execFileSync("git", ["commit", "-q", "--allow-empty", "-m", "init"], { cwd: dir });
+    return dir;
+}
+test("materialization writes verified bytes to an ignored, contained path — twice", async () => {
+    process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-inputs-blobs-"));
+    const bytes = Buffer.concat([Buffer.from("tar-bytes-"), randomBytes(64)]);
+    const staged = await stageSourceAttachments([FILE_ATTACHMENT, LINK_ATTACHMENT], {
+        fetchImpl: downloadDouble(bytes, { streamed: false }),
+    });
+    const worktree = initWorktree();
+    try {
+        const records = storeStagedAttachments("issue-1", staged);
+        const manifest = records.filter((r) => r.kind === "file");
+        assert.equal(manifest[0].blobPath && fs.existsSync(manifest[0].blobPath), true);
+        const first = materializeSourceAttachments(worktree, records);
+        assert.equal(first.length, 1);
+        assert.equal(first[0].relativePath, ".agent-dealer-inputs/linear/repro.tar.gz");
+        const dest = path.join(worktree, first[0].relativePath);
+        assert.deepEqual(fs.readFileSync(dest), bytes);
+        assert.equal(first[0].sha256, createHash("sha256").update(bytes).digest("hex"));
+        // Repair/retry stability: re-materializing yields identical bytes.
+        const second = materializeSourceAttachments(worktree, records);
+        assert.deepEqual(second, first);
+        assert.deepEqual(fs.readFileSync(dest), bytes);
+        // Ignored: the inputs root is in git info/exclude and status stays clean.
+        const excludeOut = execFileSync("git", ["-C", worktree, "rev-parse", "--git-path", "info/exclude"], {
+            encoding: "utf8",
+        });
+        const exclude = fs.readFileSync(path.resolve(worktree, excludeOut.trim()), "utf8");
+        assert.ok(exclude.split("\n").includes(LINEAR_INPUT_EXCLUDE_LINE));
+        assert.equal(execFileSync("git", ["-C", worktree, "status", "--porcelain"], { encoding: "utf8" }), "");
+        // Never auto-extracted: exactly one file landed, no directory expansion.
+        const landed = fs.readdirSync(path.join(worktree, ".agent-dealer-inputs", "linear"));
+        assert.deepEqual(landed, ["repro.tar.gz"]);
+    }
+    finally {
+        discardStaged(staged);
+        fs.rmSync(worktree, { recursive: true, force: true });
+    }
+});
+test("materialization fails closed on missing or corrupt blobs", () => {
+    const worktree = initWorktree();
+    try {
+        assert.throws(() => materializeSourceAttachments(worktree, [
+            {
+                linearAttachmentId: "a",
+                kind: "file",
+                title: "gone.bin",
+                safeFileName: "gone.bin",
+                blobPath: path.join(worktree, "no-such-blob"),
+                sha256: "0".repeat(64),
+                url: HOSTED,
+            },
+        ]), /missing/);
+        const blob = path.join(os.tmpdir(), `dealer-corrupt-blob-${Date.now()}.bin`);
+        fs.writeFileSync(blob, Buffer.from("tampered"));
+        assert.throws(() => materializeSourceAttachments(worktree, [
+            {
+                linearAttachmentId: "a",
+                kind: "file",
+                title: "evil.bin",
+                safeFileName: "evil.bin",
+                blobPath: blob,
+                sha256: "1".repeat(64),
+                url: HOSTED,
+            },
+        ]), /checksum/);
+        fs.rmSync(blob, { force: true });
+    }
+    finally {
+        fs.rmSync(worktree, { recursive: true, force: true });
+    }
+});
+test("developer prompt section lists local paths and links with the trust boundary", () => {
+    const lines = sourceAttachmentsDeveloperSection([
+        {
+            linearAttachmentId: "att-file-1",
+            kind: "file",
+            title: "repro.tar.gz",
+            safeFileName: "repro.tar.gz",
+            blobPath: "/blobs/repro.tar.gz",
+            sizeBytes: 18,
+            sha256: "ab".repeat(32),
+            url: HOSTED,
+        },
+        { linearAttachmentId: "att-link-1", kind: "link", title: "Design doc", url: LINK, subtitle: "Spec" },
+    ]);
+    const text = lines.join("\n");
+    assert.ok(text.includes("## Source attachments (untrusted ticket inputs — inspect only as needed)"));
+    assert.ok(text.includes("`.agent-dealer-inputs/linear/repro.tar.gz`"));
+    assert.ok(text.includes(`link: "Design doc" — ${LINK}`));
+    assert.ok(text.includes("never commit them"));
+    assert.ok(text.includes("never extract archives outside a fresh contained directory"));
+    assert.ok(text.includes("never fetch external-link targets automatically"));
+    assert.equal(sourceAttachmentsDeveloperSection([]).length, 0);
+    assert.equal(sourceAttachmentsDeveloperSection(undefined).length, 0);
+});
+// NOT-367: Linear's upload host authenticates like GraphQL — the snapshot
+// download must carry Authorization: <LINEAR_API_KEY>, and a 401 must read
+// as an auth failure, never as an expired URL.
+async function withLinearApiKey(value, fn) {
+    const prev = process.env.LINEAR_API_KEY;
+    if (value === undefined)
+        delete process.env.LINEAR_API_KEY;
+    else
+        process.env.LINEAR_API_KEY = value;
+    try {
+        return await fn();
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.LINEAR_API_KEY;
+        else
+            process.env.LINEAR_API_KEY = prev;
+    }
+}
+test("staging sends the Linear API key as Authorization on hosted downloads", async () => {
+    await withLinearApiKey("lin_test_key", async () => {
+        const bytes = Buffer.from("auth-bytes");
+        const seenInit = [];
+        const staged = await stageSourceAttachments([FILE_ATTACHMENT], {
+            fetchImpl: async (url, init) => {
+                seenInit.push(init);
+                return downloadDouble(bytes)(url);
+            },
+        });
+        try {
+            assert.equal(staged.files.length, 1);
+            assert.equal(seenInit.length, 1);
+            assert.equal(seenInit[0]?.headers?.Authorization, "lin_test_key");
+        }
+        finally {
+            discardStaged(staged);
+        }
+    });
+});
+test("staging invents no credentials when LINEAR_API_KEY is missing", async () => {
+    await withLinearApiKey(undefined, async () => {
+        const bytes = Buffer.from("no-key-bytes");
+        let captured;
+        const staged = await stageSourceAttachments([FILE_ATTACHMENT], {
+            fetchImpl: async (url, init) => {
+                captured = init;
+                return downloadDouble(bytes)(url);
+            },
+        });
+        try {
+            assert.equal(staged.files.length, 1, "the attempt still goes out unauthenticated");
+            assert.ok(!captured?.headers?.Authorization, "no Authorization header is invented");
+        }
+        finally {
+            discardStaged(staged);
+        }
+    });
+});
+test("staging reports HTTP 401 as rejected credentials when a key is configured", async () => {
+    await withLinearApiKey("lin_test_key", async () => {
+        const fetchImpl = async () => ({
+            ok: false,
+            status: 401,
+            headers: { get: () => null },
+        });
+        await assert.rejects(() => stageSourceAttachments([FILE_ATTACHMENT], { fetchImpl }), (err) => {
+            assert.ok(err instanceof SourceAttachmentError);
+            assert.equal(err.httpStatus, 502);
+            assert.match(err.message, /HTTP 401/);
+            assert.match(err.message, /Unauthorized/);
+            assert.match(err.message, /rejected the download credentials/);
+            assert.match(err.message, /LINEAR_API_KEY/);
+            assert.ok(!/expired/i.test(err.message), "a 401 must not blame URL expiry");
+            assert.match(err.message, /Nothing was queued/);
+            return true;
+        });
+    });
+});
+test("staging reports HTTP 401 as missing credentials when no key is configured", async () => {
+    await withLinearApiKey(undefined, async () => {
+        const fetchImpl = async () => ({
+            ok: false,
+            status: 401,
+            headers: { get: () => null },
+        });
+        await assert.rejects(() => stageSourceAttachments([FILE_ATTACHMENT], { fetchImpl }), (err) => {
+            assert.ok(err instanceof SourceAttachmentError);
+            assert.equal(err.httpStatus, 502);
+            assert.match(err.message, /HTTP 401/);
+            assert.match(err.message, /Unauthorized/);
+            assert.match(err.message, /LINEAR_API_KEY is not configured/);
+            assert.ok(!/expired/i.test(err.message), "a 401 must not blame URL expiry");
+            return true;
+        });
+    });
+});
+test("a 401 on the second file fails the whole staging with nothing returned", async () => {
+    await withLinearApiKey("lin_test_key", async () => {
+        const second = { id: "att-file-2", title: "b.bin", url: `${HOSTED}-b` };
+        const fetchImpl = async (url) => {
+            if (url === HOSTED)
+                return downloadDouble(Buffer.from("first-bytes"))(url);
+            return { ok: false, status: 401, headers: { get: () => null } };
+        };
+        await assert.rejects(() => stageSourceAttachments([FILE_ATTACHMENT, second], { fetchImpl }), (err) => {
+            assert.ok(err instanceof SourceAttachmentError);
+            assert.match(err.message, /Unauthorized/);
+            assert.match(err.message, /Nothing was queued/);
+            return true;
+        });
+    });
+});
+test("reviewer prompt section carries manifest metadata, never paths or bytes", () => {
+    const lines = sourceAttachmentsReviewerSection([
+        {
+            linearAttachmentId: "att-file-1",
+            kind: "file",
+            title: "repro.tar.gz",
+            safeFileName: "repro.tar.gz",
+            blobPath: "/blobs/repro.tar.gz",
+            sizeBytes: 18,
+            sha256: "ab".repeat(32),
+            contentType: "application/gzip",
+            url: HOSTED,
+        },
+        { linearAttachmentId: "att-link-1", kind: "link", title: "Design doc", url: LINK },
+    ]);
+    const text = lines.join("\n");
+    assert.ok(text.includes("metadata only, no file contents"));
+    assert.ok(text.includes('"repro.tar.gz"'));
+    assert.ok(text.includes("18 bytes"));
+    assert.ok(!text.includes(".agent-dealer-inputs"), "no worktree path is promised to reviewers");
+    assert.ok(!text.includes("/blobs/"), "server blob paths stay server-side");
+});

package/bundle/server/dist/coordinator/source-reload.js

@@ -0,0 +1,178 @@
+// packages/server/src/coordinator/source-reload.ts
+// NOT-363: reload a Linear-sourced issue's task text from its linked ticket.
+//
+// Before the workflow snapshot freezes, an operator can pull the latest title
+// and description from Linear. The shared execution-contract compiler rebuilds
+// the contract from the refreshed description, and the derived acceptance
+// criteria replace whatever the issue carried — old local criteria never
+// survive a source reload. Repository, base branch, agent assignments, policy
+// limits, auto-merge, queue position, and every coordinator-owned field are
+// untouched; nothing is written back to Linear.
+import { createHash } from "node:crypto";
+import { compileExecutionContract, ExecutionContractError, } from "@agent-dealer/shared";
+import { getDb } from "../db/index.js";
+import { getIssue } from "../repository/issues.js";
+import { appendWorkflowEvent, getActiveWorkflowInstance } from "../repository/workflow-events.js";
+import { getActiveWorkerSessionForIssue } from "../repository/worker-sessions.js";
+import { getLinearIssue } from "../adapters/linear-inbox.js";
+import { discardStaged, pruneDisusedBlobs, pruneUncommittedBlobs, SourceAttachmentError, stageSourceAttachments, storeStagedAttachments, } from "./source-attachments.js";
+import { listSourceAttachments, replaceSourceAttachments, } from "../repository/source-attachments.js";
+/** Short digest of task text for the timeline payload — never the full text. */
+export function digestTaskText(text) {
+    return createHash("sha256").update(text ?? "").digest("hex").slice(0, 16);
+}
+/**
+ * NOT-363: the issue must still be pre-execution — `ready` with no active
+ * workflow and no running worker. Anything else answers 409 and changes
+ * nothing, so a reload that races admission fails closed instead of landing
+ * on a live snapshot.
+ */
+function reloadConflict(issue) {
+    if (issue.status !== "ready") {
+        return `Cannot reload the source of an issue that is ${issue.status}`;
+    }
+    if (getActiveWorkerSessionForIssue(issue.id)) {
+        return "Cannot reload the source of an issue with an actively running session";
+    }
+    if (getActiveWorkflowInstance(issue.id)) {
+        return "Cannot reload the source of an issue with an active workflow";
+    }
+    return null;
+}
+/**
+ * One explicit server operation: fetch the linked Linear ticket through the
+ * direct GraphQL adapter, replace title + description atomically, recompile
+ * the execution contract, and replace the acceptance criteria with the
+ * criteria derived from the refreshed description.
+ *
+ * `fetchLinearIssue` is injectable for tests; production passes the shared
+ * `getLinearIssue` adapter. The Linear fetch happens outside the write
+ * transaction, and the pre-execution guard runs twice — once for the fast
+ * path, once inside the transaction — so a race with admission answers 409
+ * with no partial write and no timeline event.
+ */
+export async function reloadIssueSourceFromLinear(issueId, opts) {
+    const issue = getIssue(issueId);
+    if (!issue)
+        return { ok: false, code: 404, error: "Not found" };
+    if (issue.source !== "linear") {
+        return { ok: false, code: 400, error: "Only Linear-sourced issues can be reloaded from Linear" };
+    }
+    if (!issue.externalId) {
+        return { ok: false, code: 400, error: "Issue has no linked Linear ticket to reload from" };
+    }
+    const fastPath = reloadConflict(issue);
+    if (fastPath)
+        return { ok: false, code: 409, error: fastPath };
+    const fetchLinearIssue = opts?.fetchLinearIssue ?? getLinearIssue;
+    let candidate;
+    try {
+        candidate = await fetchLinearIssue(issue.externalId);
+    }
+    catch (err) {
+        return { ok: false, code: 502, error: `Linear reload failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (!candidate) {
+        return { ok: false, code: 404, error: "Linear issue not found — it may have been deleted" };
+    }
+    // NOT-363: the same title convention as import (`<identifier>: <title>`);
+    // the description mirrors import (trimmed, empty falls back to null) so a
+    // reload and a fresh import of the same ticket agree field-for-field.
+    const nextTitle = `${candidate.identifier}: ${candidate.title}`;
+    const nextDescription = candidate.description?.trim() ? candidate.description : null;
+    // A source refresh recompiles through the shared compiler — an
+    // ambiguous/malformed refreshed description is a 400 with an actionable
+    // message, never a silent half-parse and never a partial write.
+    let nextAcceptanceCriteria;
+    try {
+        nextAcceptanceCriteria = compileExecutionContract(nextDescription).acceptanceCriteria;
+    }
+    catch (err) {
+        if (err instanceof ExecutionContractError) {
+            return { ok: false, code: 400, error: err.message };
+        }
+        throw err;
+    }
+    const prevTitleDigest = digestTaskText(issue.title);
+    const prevDescriptionDigest = digestTaskText(issue.description);
+    // NOT-364: staged all-or-nothing attachment reconciliation, reusing the same
+    // operation as import. Every hosted file downloads (and the refreshed
+    // contract compiles) BEFORE the write transaction; staged bytes land on
+    // content-addressed paths the live rows never reference, and the rows then
+    // swap inside that transaction, so a failed reload preserves the old task
+    // text AND the old attachment snapshot (old blob bytes stay verifiable).
+    // Removed Linear files disappear from the pre-execution snapshot; their
+    // blobs are pruned after a successful commit.
+    const prevAttachments = listSourceAttachments(issueId);
+    let staged = null;
+    try {
+        staged = await stageSourceAttachments(candidate.attachments);
+    }
+    catch (err) {
+        if (err instanceof SourceAttachmentError) {
+            return { ok: false, code: err.httpStatus, error: err.message };
+        }
+        throw err;
+    }
+    let nextAttachmentRecords;
+    try {
+        nextAttachmentRecords = storeStagedAttachments(issueId, staged);
+    }
+    finally {
+        discardStaged(staged);
+    }
+    try {
+        const updated = getDb().transaction(() => {
+            const fresh = getIssue(issueId);
+            if (!fresh)
+                throw Object.assign(new Error("Not found"), { code: 404 });
+            const conflict = reloadConflict(fresh);
+            if (conflict)
+                throw Object.assign(new Error(conflict), { code: 409 });
+            const now = new Date().toISOString();
+            getDb()
+                .prepare(`UPDATE issues SET title = @title, description = @description,
+           acceptance_criteria = @acceptance_criteria, updated_at = @updated_at WHERE id = @id`)
+                .run({
+                id: issueId,
+                title: nextTitle,
+                description: nextDescription,
+                acceptance_criteria: nextAcceptanceCriteria,
+                updated_at: now,
+            });
+            replaceSourceAttachments(issueId, nextAttachmentRecords);
+            appendWorkflowEvent({
+                issueId,
+                type: "issue.source_reloaded",
+                actorType: "human",
+                stage: fresh.status,
+                payload: {
+                    source: "linear",
+                    externalId: fresh.externalId,
+                    externalLabel: fresh.externalLabel,
+                    prevTitleDigest,
+                    newTitleDigest: digestTaskText(nextTitle),
+                    prevDescriptionDigest,
+                    newDescriptionDigest: digestTaskText(nextDescription),
+                },
+            });
+            const next = getIssue(issueId);
+            if (!next)
+                throw Object.assign(new Error("Not found"), { code: 404 });
+            return next;
+        })();
+        pruneDisusedBlobs(prevAttachments, nextAttachmentRecords);
+        return { ok: true, issue: updated };
+    }
+    catch (err) {
+        // The staged bytes landed on content-addressed paths the old rows never
+        // reference, so the prior snapshot is intact — drop the orphaned new
+        // blobs before answering.
+        pruneUncommittedBlobs(prevAttachments, nextAttachmentRecords);
+        const code = err.code;
+        const message = err instanceof Error ? err.message : String(err);
+        if (code === 404 || code === 409)
+            return { ok: false, code, error: message };
+        throw err;
+    }
+}

package/bundle/server/dist/db/index.js

@@ -412,6 +412,10 @@ export function migrate() {
     if (!capacityCols.some((c) => c.name === "critical_role")) {
         db.exec("ALTER TABLE runtime_capacity_snapshots ADD COLUMN critical_role TEXT");
     }
+    // NOT-366: acquisition-failure streak on a table that predates it.
+    if (!capacityCols.some((c) => c.name === "unavailable_detail")) {
+        db.exec("ALTER TABLE runtime_capacity_snapshots ADD COLUMN unavailable_detail TEXT");
+    }
     // NOT-249: normalized Cursor-team billing snapshot for databases created
     // before schema.sql declared the table (same upgrade-path pattern as
     // runtime_capacity_snapshots above).

package/bundle/server/dist/db/schema.sql

@@ -411,6 +411,10 @@ CREATE TABLE IF NOT EXISTS runtime_capacity_snapshots (
   -- it collapsed into) — never re-derived client-side from a window key or
   -- label, which cannot disambiguate multiple same-duration buckets.
   critical_role TEXT,
+  -- NOT-366: JSON acquisition-failure streak for an unavailable row
+  -- (operator summary, consecutive-failure count, first/last failure time).
+  -- Null on every successful reading.
+  unavailable_detail TEXT,
   PRIMARY KEY (runtime, window_key)
 );
 
@@ -566,3 +570,31 @@ CREATE INDEX IF NOT EXISTS idx_queue_entries_queued_position
   ON queue_entries(position) WHERE state = 'queued';
 -- NOT-173: the read model loads every queue-entry row for an issue set.
 CREATE INDEX IF NOT EXISTS idx_queue_entries_issue ON queue_entries(issue_id);
+
+-- NOT-364: durable snapshots of a Linear issue's own file/link attachments.
+-- One row per (issue, Linear attachment id): hosted files carry a Dealer-owned
+-- blob_path plus integrity fields so a queued Builder never needs the
+-- expiring Linear URL; links carry source metadata only. Blobs live under
+-- <datadir>/source-attachments/<issueId>/ and are retained with the issue
+-- history (there is no hard delete — `closed` issues stay queryable).
+CREATE TABLE IF NOT EXISTS issue_source_attachments (
+  id TEXT PRIMARY KEY,
+  issue_id TEXT NOT NULL REFERENCES issues(id),
+  linear_attachment_id TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('file', 'link')),
+  title TEXT NOT NULL,
+  safe_file_name TEXT,
+  blob_path TEXT,
+  content_type TEXT,
+  size_bytes INTEGER,
+  sha256 TEXT,
+  url TEXT NOT NULL,
+  subtitle TEXT,
+  source TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_issue_source_attachments_issue_linear
+  ON issue_source_attachments(issue_id, linear_attachment_id);
+CREATE INDEX IF NOT EXISTS idx_issue_source_attachments_issue
+  ON issue_source_attachments(issue_id);

package/bundle/server/dist/docs-linear-attachments.test.js

@@ -0,0 +1,36 @@
+// NOT-364: docs/LINEAR_INTEGRATION.md is the canonical issue-attachment
+// contract — durability, limits, trust boundary, and the comment-only
+// exclusion must stay stated there, and the stated limits must match code.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { MAX_SOURCE_ATTACHMENT_FILE_BYTES, MAX_SOURCE_ATTACHMENT_TOTAL_BYTES, } from "./coordinator/source-attachments.js";
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+const doc = fs.readFileSync(path.join(repoRoot, "docs/LINEAR_INTEGRATION.md"), "utf8");
+test("the Linear doc states attachment durability, limits, trust, and exclusions", () => {
+    for (const phrase of [
+        "### Issue attachments (NOT-364)",
+        "100 MiB per file",
+        "250 MiB total per issue",
+        "External links",
+        "never downloaded",
+        "comments",
+        "never auto-extracted",
+        "untrusted ticket inputs",
+        "never commit them",
+        "fresh contained directory",
+        ".agent-dealer-inputs/linear/",
+        "Reload from Linear",
+        "Reviewers receive the manifest metadata only",
+    ]) {
+        assert.ok(doc.includes(phrase), `LINEAR_INTEGRATION.md must state: ${phrase}`);
+    }
+    // The stale line claiming attachments are never imported is gone.
+    assert.ok(!doc.includes("attachments are not imported"));
+});
+test("documented limits match the enforced snapshot caps", () => {
+    assert.equal(MAX_SOURCE_ATTACHMENT_FILE_BYTES, 100 * 1024 * 1024);
+    assert.equal(MAX_SOURCE_ATTACHMENT_TOTAL_BYTES, 250 * 1024 * 1024);
+});