agent-dealer 1.2.13 → 1.2.14

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

@@ -0,0 +1,284 @@
+// 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);
+});
+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/schema.sql

@@ -566,3 +566,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);
+});

package/bundle/server/dist/paths.js

@@ -35,6 +35,18 @@ export function cleanupOrphanedWorkerMcpConfig() {
         fs.rmSync(path.join(dir, entry), { recursive: true, force: true });
     }
 }
+/**
+ * NOT-364: Dealer-owned blobs for Linear issue-source attachments. Content is
+ * addressed under `<dir>/<issueId>/`; rows in `issue_source_attachments` point
+ * here. Retained with the issue history — worktree copies are removed with
+ * normal worktree cleanup, but these blobs survive until the issue row itself
+ * is gone (and there is no hard-delete path: `closed` issues stay queryable).
+ */
+export function getSourceAttachmentsDir() {
+    const dir = path.join(getDataDir(), "source-attachments");
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
 /**
  * Root for Dealer-managed repository clones and session worktrees (NOT-149).
  * Defaults under AGENT_DEALER_HOME; override with AGENT_DEALER_EXECUTION_ROOT for a

package/bundle/server/dist/repository/source-attachments.js

@@ -0,0 +1,56 @@
+// packages/server/src/repository/source-attachments.ts
+//
+// NOT-364: read/write side for `issue_source_attachments` — durable snapshots
+// of a Linear issue's own file/link attachments, keyed by
+// (Dealer issue id, Linear attachment id). Hosted files carry a Dealer-owned
+// blob_path plus integrity fields; links carry source metadata only.
+import { v4 as uuid } from "uuid";
+import { getDb } from "../db/index.js";
+function rowToRecord(row) {
+    const out = {
+        linearAttachmentId: row.linear_attachment_id,
+        kind: row.kind === "file" ? "file" : "link",
+        title: row.title,
+        url: row.url,
+    };
+    if (row.safe_file_name)
+        out.safeFileName = row.safe_file_name;
+    if (row.blob_path)
+        out.blobPath = row.blob_path;
+    if (row.content_type)
+        out.contentType = row.content_type;
+    if (row.size_bytes !== null)
+        out.sizeBytes = row.size_bytes;
+    if (row.sha256)
+        out.sha256 = row.sha256;
+    if (row.subtitle)
+        out.subtitle = row.subtitle;
+    if (row.source)
+        out.source = row.source;
+    return out;
+}
+/** Every source attachment for the issue, oldest first (stable prompt order). */
+export function listSourceAttachments(issueId) {
+    const rows = getDb()
+        .prepare("SELECT * FROM issue_source_attachments WHERE issue_id = ? ORDER BY created_at ASC, rowid ASC")
+        .all(issueId);
+    return rows.map(rowToRecord);
+}
+/**
+ * All-or-nothing replacement of an issue's attachment snapshot: deletes every
+ * existing row for the issue, then inserts the new set. Call inside the
+ * caller's transaction when the replacement must commit atomically with other
+ * writes (import text, reload text) — a throw leaves the prior rows untouched.
+ */
+export function replaceSourceAttachments(issueId, records) {
+    const db = getDb();
+    const now = new Date().toISOString();
+    db.prepare("DELETE FROM issue_source_attachments WHERE issue_id = ?").run(issueId);
+    const insert = db.prepare(`INSERT INTO issue_source_attachments
+      (id, issue_id, linear_attachment_id, kind, title, safe_file_name, blob_path,
+       content_type, size_bytes, sha256, url, subtitle, source, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    for (const r of records) {
+        insert.run(uuid(), issueId, r.linearAttachmentId, r.kind, r.title, r.safeFileName ?? null, r.blobPath ?? null, r.contentType ?? null, r.sizeBytes ?? null, r.sha256 ?? null, r.url, r.subtitle ?? null, r.source ?? null, now, now);
+    }
+}

package/bundle/server/dist/routes/human-actions.js

@@ -2,6 +2,7 @@ import { getHumanAction, listOpenHumanActions } from "../repository/human-action
 import { resolveHumanActionAndAdvanceAsync } from "../coordinator/commands.js";
 import { normalizeResolutionNote } from "../coordinator/human-resolution.js";
 import { triggerIssueReflect, resolveReflectionInteractionAction } from "../coordinator/reflect-trigger.js";
+import { isLinearMergeStaleAction, resolveLinearMergeStaleAction, } from "../coordinator/linear-merge-verify.js";
 import { resolveOutboundDeliveryAction } from "../queue/approve-deliver.js";
 export async function registerHumanActionRoutes(app) {
     app.get("/api/human-actions", async () => listOpenHumanActions());
@@ -50,6 +51,22 @@ export async function registerHumanActionRoutes(app) {
                 return reply.status(deliveryResult.code).send({ error: deliveryResult.error });
             return { runStatus: deliveryResult.runStatus, delivered: deliveryResult.delivered };
         }
+        // NOT-362: the stale-source notice sits on an already-`done` issue with no
+        // active workflow to advance — the generic resolver would 409 on "no active
+        // workflow for this action" and the notice could never close. Resolve it
+        // directly (same shape as the reflection branch above); `recheck` re-runs
+        // the post-merge verification fire-and-forget.
+        if (action.actionType === "policy_escalation" && isLinearMergeStaleAction(action)) {
+            const staleResult = resolveLinearMergeStaleAction(id, resolvedBy, choice);
+            if (!staleResult.ok)
+                return reply.status(staleResult.code).send({ error: staleResult.error });
+            return {
+                issueStatus: staleResult.issueStatus,
+                nextWorkItemId: null,
+                instanceCompleted: false,
+                restarted: false,
+            };
+        }
         // Awaits undraft+merge when final_review:complete (NOT-102) — sync resolve alone would
         // only park at AUTO_MERGE_INTENT and leave the PR draft.
         const result = await resolveHumanActionAndAdvanceAsync(id, resolvedBy, choice, {