agent-dealer 1.2.7 → 1.2.8

package/bundle/server/dist/repository/artifacts-for-issue.js

@@ -23,10 +23,10 @@ export function listArtifactsForIssue(issueId, opts) {
     const limit = opts?.limit ?? 50;
     const rows = opts?.before
         ? getDb()
-            .prepare("SELECT * FROM artifacts WHERE issue_id = ? AND created_at < ? ORDER BY created_at DESC LIMIT ?")
+            .prepare("SELECT * FROM artifacts WHERE issue_id = ? AND created_at < ? ORDER BY created_at DESC, rowid DESC LIMIT ?")
             .all(issueId, opts.before, limit)
         : getDb()
-            .prepare("SELECT * FROM artifacts WHERE issue_id = ? ORDER BY created_at DESC LIMIT ?")
+            .prepare("SELECT * FROM artifacts WHERE issue_id = ? ORDER BY created_at DESC, rowid DESC LIMIT ?")
             .all(issueId, limit);
     return rows.map(rowToArtifact);
 }
@@ -36,7 +36,7 @@ export function listArtifactsForIssue(issueId, opts) {
  * scan) can't have an old row fall outside the window on an artifact-heavy issue. */
 export function listArtifactsForIssueByKind(issueId, kind) {
     const rows = getDb()
-        .prepare("SELECT * FROM artifacts WHERE issue_id = ? AND kind = ? ORDER BY created_at DESC")
+        .prepare("SELECT * FROM artifacts WHERE issue_id = ? AND kind = ? ORDER BY created_at DESC, rowid DESC")
         .all(issueId, kind);
     return rows.map(rowToArtifact);
 }

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

@@ -119,6 +119,20 @@ export function findOpenHumanActionByRequestId(issueId, actionType, requestId) {
         .get(issueId, actionType, requestId);
     return row ? rowToAction(row) : null;
 }
+/**
+ * NOT-308: version-scoped Muse capability escalations live on whichever issue first
+ * observed the verdict, but later admissions for *other* issues must find the same
+ * action instead of raising a duplicate — so the lookup is by (type, request_id)
+ * across issues, not per issue. Returns open actions first so callers can skip
+ * creation; resolved ones are included so callers can distinguish "already handled".
+ */
+export function listHumanActionsByRequestId(actionType, requestId) {
+    const rows = getDb()
+        .prepare(`SELECT * FROM human_actions WHERE action_type = ? AND request_id = ?
+       ORDER BY CASE status WHEN 'open' THEN 0 ELSE 1 END, requested_at ASC`)
+        .all(actionType, requestId);
+    return rows.map(rowToAction);
+}
 export function listHumanActionsForIssue(issueId) {
     const rows = getDb()
         .prepare("SELECT * FROM human_actions WHERE issue_id = ? ORDER BY requested_at ASC")

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

@@ -1,4 +1,4 @@
-import { canTransitionIssue, CreateIssueInput, looksLikeLocalRepoPath, parseGitHubRepoInput, TERMINAL_ISSUE_STATUSES, } from "@agent-dealer/shared";
+import { canTransitionIssue, compileExecutionContract, CreateIssueInput, looksLikeLocalRepoPath, parseGitHubRepoInput, resolveIssueContractFields, tryCompileContract, TERMINAL_ISSUE_STATUSES, } from "@agent-dealer/shared";
 import { v4 as uuid } from "uuid";
 import { getDb } from "../db/index.js";
 function rowToIssue(row) {
@@ -11,6 +11,11 @@ function rowToIssue(row) {
         title: row.title,
         description: row.description,
         acceptanceCriteria: row.acceptance_criteria,
+        // NOT-306: the contract is derived from the stored description on every
+        // read — the description stays the untouched source of truth, so no
+        // migration or second authoring surface exists. A description that fails
+        // validation (written before validation existed) reads as a legacy null.
+        executionContract: tryCompileContract(row.description),
         repo: row.repo,
         baseBranch: row.base_branch,
         status: row.status,
@@ -49,6 +54,12 @@ export function createIssue(raw) {
     const { repo: repoRaw, ...rest } = raw;
     const input = CreateIssueInput.omit({ repo: true }).parse(rest);
     const repo = normalizeStoredIssueRepo(repoRaw);
+    // NOT-306: validate the ticket's execution contract here so every creation
+    // path (web, API, CLI-via-API, Linear import) shares one compiler — an
+    // ambiguous/malformed contract throws instead of silently dropping fields.
+    // A missing explicit acceptanceCriteria is filled from the description; an
+    // explicit value always wins and the description is stored untouched.
+    const resolved = resolveIssueContractFields(input.description, input.acceptanceCriteria);
     const db = getDb();
     const now = new Date().toISOString();
     const id = uuid();
@@ -60,7 +71,7 @@ export function createIssue(raw) {
         external_url: input.externalUrl ?? null,
         title: input.title,
         description: input.description ?? null,
-        acceptance_criteria: input.acceptanceCriteria ?? null,
+        acceptance_criteria: resolved.acceptanceCriteria,
         repo,
         base_branch: input.baseBranch,
         status: "ready",
@@ -263,6 +274,20 @@ export function updateIssue(id, patch) {
     const current = getIssue(id);
     if (!current)
         throw new Error(`Issue not found: ${id}`);
+    // NOT-306: an edited description recompiles through the same compiler as
+    // creation — an ambiguous/malformed contract throws instead of landing
+    // half-parsed. A missing acceptanceCriteria is backfilled from the new
+    // description only when the issue has none; an explicit value always wins.
+    // Validation runs only when the patch touches the description, so unrelated
+    // updates (e.g. a base-branch-only sync) never fail on a stored description
+    // that predates validation.
+    const nextDescription = patch.description !== undefined ? patch.description : current.description;
+    const compiled = patch.description !== undefined ? compileExecutionContract(nextDescription) : null;
+    const nextAcceptanceCriteria = patch.acceptanceCriteria !== undefined
+        ? patch.acceptanceCriteria
+        : current.acceptanceCriteria?.trim()
+            ? current.acceptanceCriteria
+            : (compiled?.acceptanceCriteria ?? current.acceptanceCriteria);
     const now = new Date().toISOString();
     getDb()
         .prepare(`
@@ -283,8 +308,8 @@ export function updateIssue(id, patch) {
         .run({
         id,
         title: patch.title ?? current.title,
-        description: patch.description !== undefined ? patch.description : current.description,
-        acceptance_criteria: patch.acceptanceCriteria !== undefined ? patch.acceptanceCriteria : current.acceptanceCriteria,
+        description: nextDescription,
+        acceptance_criteria: nextAcceptanceCriteria,
         repo: patch.repo !== undefined ? normalizeStoredIssueRepo(patch.repo) : current.repo,
         base_branch: patch.baseBranch ?? current.baseBranch,
         developer_agent_id: patch.developerAgentId ?? current.developerAgentId,

package/bundle/server/dist/repository/worker-sessions.js

@@ -22,6 +22,7 @@ function rowToSession(row) {
         processPid: row.process_pid,
         processOwner: row.process_owner,
         processStartedAt: row.process_started_at,
+        deckCorrelationId: row.deck_correlation_id ?? null,
         createdAt: row.created_at,
         startedAt: row.started_at,
         heartbeatAt: row.heartbeat_at,
@@ -53,6 +54,9 @@ export function createWorkerSession(input) {
         process_pid: null,
         process_owner: null,
         process_started_at: null,
+        // NOT-305: one opaque Deck correlation UUID per session, persisted before spawn so
+        // every runtime launch config can carry it as observability metadata.
+        deck_correlation_id: uuid(),
         created_at: now,
         started_at: null,
         heartbeat_at: null,
@@ -63,17 +67,35 @@ export function createWorkerSession(input) {
     INSERT INTO worker_sessions (
       id, issue_id, role, round, agent_id, runtime, model, budget_json, worktree_path,
       input_sha, status, session_ref, log_path, exit_code, error_json, metadata_json,
-      profile_snapshot_json, process_pid, process_owner, process_started_at, created_at, started_at, heartbeat_at,
+      profile_snapshot_json, process_pid, process_owner, process_started_at, deck_correlation_id, created_at, started_at, heartbeat_at,
       completed_at, updated_at
     ) VALUES (
       @id, @issue_id, @role, @round, @agent_id, @runtime, @model, @budget_json, @worktree_path,
       @input_sha, @status, @session_ref, @log_path, @exit_code, @error_json, @metadata_json,
-      @profile_snapshot_json, @process_pid, @process_owner, @process_started_at, @created_at, @started_at, @heartbeat_at,
+      @profile_snapshot_json, @process_pid, @process_owner, @process_started_at, @deck_correlation_id, @created_at, @started_at, @heartbeat_at,
       @completed_at, @updated_at
     )
   `).run(row);
     return rowToSession(row);
 }
+/**
+ * NOT-305: returns the session's Deck correlation UUID, assigning and persisting one
+ * when a pre-feature row has none. New rows always carry one from creation; this only
+ * repairs rows written before the column existed so their launch configs and receipts
+ * still correlate. Returns null when the session does not exist.
+ */
+export function getOrAssignSessionCorrelationId(id) {
+    const current = getWorkerSession(id);
+    if (!current)
+        return null;
+    if (current.deckCorrelationId)
+        return current.deckCorrelationId;
+    const correlationId = uuid();
+    getDb()
+        .prepare("UPDATE worker_sessions SET deck_correlation_id = ?, updated_at = ? WHERE id = ?")
+        .run(correlationId, new Date().toISOString(), id);
+    return correlationId;
+}
 export function getWorkerSession(id) {
     const row = getDb().prepare("SELECT * FROM worker_sessions WHERE id = ?").get(id);
     return row ? rowToSession(row) : null;
@@ -165,6 +187,33 @@ export function recordSessionProcess(id, pid, owner, startTime = null) {
        WHERE id = ? AND status = 'running'`)
         .run(pid, owner, startTime, new Date().toISOString(), id);
 }
+/**
+ * NOT-307: shallow-merges `patch` into the session's `metadata_json` (read +
+ * JSON-merge + write; unparseable existing content restarts from `{}`). Works on
+ * any status — the Muse lane records stall evidence right after spawn, before the
+ * terminal `completeSession`. No-op for unknown ids; never throws for malformed
+ * JSON. Callers needing atomicity should not use this (it is best-effort evidence).
+ */
+export function mergeSessionMetadata(id, patch) {
+    const current = getWorkerSession(id);
+    if (!current)
+        return;
+    let base = {};
+    if (current.metadataJson) {
+        try {
+            const parsed = JSON.parse(current.metadataJson);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                base = parsed;
+            }
+        }
+        catch {
+            base = {};
+        }
+    }
+    getDb()
+        .prepare("UPDATE worker_sessions SET metadata_json = ?, updated_at = ? WHERE id = ?")
+        .run(JSON.stringify({ ...base, ...patch }), new Date().toISOString(), id);
+}
 /** Most recent still-running session for an issue — drives the Issue Detail live strip. */
 export function getActiveWorkerSessionForIssue(issueId) {
     const row = getDb()

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

@@ -57,14 +57,16 @@ export async function registerHumanActionRoutes(app) {
         });
         if (!result.ok)
             return reply.status(result.code).send({ error: result.error });
-        // Reflect is a best-effort network call to Agent Deck (health check + a sequential
-        // fetch/propose round trip per playbook) — resolution has already committed above, so
-        // this must not hold the HTTP response hostage behind it: a slow/offline deck would
-        // otherwise risk a client timeout on an already-resolved action, whose retry then gets
-        // a spurious 409. Fire-and-forget; triggerIssueReflect never throws (it records its own
-        // outcome as artifacts), so there is nothing here to await or react to.
-        // triggerReflect is set after a successful merge-to-done (auto-merge or human complete).
-        if (result.triggerReflect && action.issueId) {
+        // NOT-305: completion evidence is a best-effort Deck read (receipts) plus at most
+        // one `signal_only` report per failure/correction trigger — resolution has already
+        // committed above, so this must not hold the HTTP response hostage behind it: a
+        // slow/offline deck would otherwise risk a client timeout on an already-resolved
+        // action, whose retry then gets a spurious 409. Fire-and-forget; triggerIssueReflect
+        // never throws (it records its own outcome as artifacts), so there is nothing here
+        // to await or react to. Fires for every instance-completing resolution (done AND
+        // closed): an attempts-exhausted close still owes its actual-use receipts and its
+        // exhaustion signal even though no merge follows.
+        if (result.instanceCompleted && action.issueId) {
             void triggerIssueReflect(action.issueId).catch(() => { });
         }
         return {

package/bundle/server/dist/routes/issues-execution-contract.test.js

@@ -0,0 +1,321 @@
+// NOT-306: Linear/Planner tickets compile into frozen execution contracts.
+// Web, API, and CLI creation all funnel through POST /api/issues, so these
+// route tests cover each intake path with its equivalent request shape while
+// the shared compiler owns the parsing (no page-local regex anywhere).
+import { test, before, after, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+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-contract-"));
+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 { getIssue } = await import("../repository/issues.js");
+const { claimWorkItem } = await import("../repository/work-items.js");
+const { listHumanActionsForIssue } = await import("../repository/human-actions.js");
+const { applyCompletion, resolveHumanActionAndAdvance, getTaskSnapshot } = await import("../coordinator/commands.js");
+const { ReviewerResult } = await import("../coordinator/reviewer-result.js");
+const { setAdmissionHealthCheckerForTests } = await import("../coordinator/admission.js");
+before(() => {
+    migrate();
+    setAdmissionHealthCheckerForTests(async () => ({ ok: true }));
+});
+after(() => setAdmissionHealthCheckerForTests(null));
+beforeEach(() => {
+    getDb().exec(`
+    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;
+}
+/** Planner-authored Linear ticket carrying every contract-v1 heading. */
+const CONTRACT_DESCRIPTION = [
+    "Compile the Planner ticket into a frozen execution contract.",
+    "",
+    "## Builder execution mode",
+    "feature",
+    "",
+    "## Non-goals",
+    "- Selecting a playbook or reasoning about implementation architecture",
+    "- Adding a generic workflow/schema editor",
+    "",
+    "## Exit predicate",
+    "Importing a Planner-authored Linear ticket yields a versioned frozen execution contract.",
+    "",
+    "## One-PR stopping point",
+    "Stop after the contract compiles, freezes, and renders in both worker prompts.",
+    "",
+    "## Acceptance criteria",
+    "- [ ] Full ticket imports into the exact structured schema",
+    "  Evidence: shared compiler fixtures | run the compiler test | every field asserted",
+    "- [ ] Legacy issues without headings still start",
+    "  Evidence: legacy suite | run the legacy tests | green",
+    "",
+].join("\n");
+const EXPECTED_CONTRACT = {
+    version: "v1",
+    executionMode: "feature",
+    nonGoals: [
+        "Selecting a playbook or reasoning about implementation architecture",
+        "Adding a generic workflow/schema editor",
+    ],
+    exitPredicate: "Importing a Planner-authored Linear ticket yields a versioned frozen execution contract.",
+    onePrStoppingPoint: "Stop after the contract compiles, freezes, and renders in both worker prompts.",
+    acceptanceCriteria: [
+        {
+            text: "Full ticket imports into the exact structured schema",
+            evidence: "shared compiler fixtures | run the compiler test | every field asserted",
+        },
+        {
+            text: "Legacy issues without headings still start",
+            evidence: "legacy suite | run the legacy tests | green",
+        },
+    ],
+};
+const BASE_AGENTS = {
+    repo: "acme/app",
+    baseBranch: "main",
+    developerAgentId: BUILTIN_AGENT_CLAUDE_ID,
+    reviewerAgentId: BUILTIN_AGENT_CURSOR_ID,
+};
+test("web/API/CLI-shaped creates compile the same contract and keep the source untouched", async () => {
+    const app = await buildApp();
+    // Web Linear import: full ticket description, no separate criteria field —
+    // the server derives it with the shared compiler.
+    const webShaped = {
+        title: "NOT-306: frozen execution contracts",
+        description: CONTRACT_DESCRIPTION,
+        source: "linear",
+        externalId: "linear-uuid-web",
+        externalLabel: "NOT-306",
+        externalUrl: "https://linear.app/not-so-fat/issue/NOT-306/x",
+        ...BASE_AGENTS,
+    };
+    // API direct create: same description plus an explicit override stays explicit.
+    const apiShaped = {
+        title: "Contract via API",
+        description: CONTRACT_DESCRIPTION,
+        acceptanceCriteria: "Operator-typed override",
+        ...BASE_AGENTS,
+    };
+    // CLI agent create: source agent, description carried through.
+    const cliShaped = {
+        title: "Contract via CLI",
+        description: CONTRACT_DESCRIPTION,
+        source: "agent",
+        ...BASE_AGENTS,
+    };
+    for (const [name, payload] of [["web", webShaped], ["api", apiShaped], ["cli", cliShaped]]) {
+        const res = await app.inject({ method: "POST", url: "/api/issues", payload });
+        assert.equal(res.statusCode, 200, `${name}: ${res.body}`);
+        const created = res.json();
+        assert.deepStrictEqual(created.executionContract, EXPECTED_CONTRACT, name);
+        assert.equal(created.description, CONTRACT_DESCRIPTION, `${name}: source Markdown stored unchanged`);
+        const detail = (await app.inject({ method: "GET", url: `/api/issues/${created.id}` })).json();
+        assert.deepStrictEqual(detail.issue.executionContract, EXPECTED_CONTRACT, `${name} detail`);
+        assert.equal(detail.issue.description, CONTRACT_DESCRIPTION, `${name} detail source unchanged`);
+    }
+    // The override wins; the derived rendering fills only when nothing was given.
+    const apiCreated = (await app.inject({ method: "POST", url: "/api/issues", payload: { ...apiShaped, title: "again" } })).json();
+    assert.equal(apiCreated.acceptanceCriteria, "Operator-typed override");
+    const webCreated = (await app.inject({ method: "POST", url: "/api/issues", payload: { ...webShaped, title: "again", externalId: "linear-uuid-web-2" } })).json();
+    assert.ok(webCreated.acceptanceCriteria.includes("- [ ] Full ticket imports into the exact structured schema"));
+    assert.ok(webCreated.acceptanceCriteria.includes("Evidence: shared compiler fixtures"));
+    await app.close();
+});
+test("a contract ticket starts — readiness is satisfied by the derived criteria", async () => {
+    const app = await buildApp();
+    const created = (await app.inject({
+        method: "POST",
+        url: "/api/issues",
+        payload: { title: "Startable contract", description: CONTRACT_DESCRIPTION, ...BASE_AGENTS },
+    })).json();
+    const startRes = await app.inject({ method: "POST", url: `/api/issues/${created.id}/start` });
+    assert.equal(startRes.statusCode, 200, startRes.body);
+    // Starting freezes the compiled contract alongside the source description.
+    const frozen = getTaskSnapshot(getIssue(created.id));
+    assert.deepStrictEqual(frozen.executionContract, EXPECTED_CONTRACT);
+    assert.equal(frozen.description, CONTRACT_DESCRIPTION);
+    await app.close();
+});
+test("legacy issues with no contract headings keep current behavior and stay startable", async () => {
+    const app = await buildApp();
+    const created = (await app.inject({
+        method: "POST",
+        url: "/api/issues",
+        payload: { title: "Legacy", description: "Just a plain description.", acceptanceCriteria: "It works", ...BASE_AGENTS },
+    })).json();
+    assert.equal(created.executionContract, null);
+    const startRes = await app.inject({ method: "POST", url: `/api/issues/${created.id}/start` });
+    assert.equal(startRes.statusCode, 200, startRes.body);
+    const frozen = getTaskSnapshot(getIssue(created.id));
+    assert.equal(frozen.executionContract, null);
+    await app.close();
+});
+test("an Acceptance-criteria-only ticket keeps the legacy extraction and stays startable", async () => {
+    const app = await buildApp();
+    const created = (await app.inject({
+        method: "POST",
+        url: "/api/issues",
+        payload: {
+            title: "AC-only legacy",
+            description: "Ship it.\n\n## Acceptance criteria\nIt works and it ships.",
+            ...BASE_AGENTS,
+        },
+    })).json();
+    assert.equal(created.executionContract, null);
+    assert.equal(created.acceptanceCriteria, "It works and it ships.");
+    const startRes = await app.inject({ method: "POST", url: `/api/issues/${created.id}/start` });
+    assert.equal(startRes.statusCode, 200, startRes.body);
+    await app.close();
+});
+const INVALID_DESCRIPTIONS = [
+    {
+        name: "unknown execution mode",
+        description: CONTRACT_DESCRIPTION.replace("feature", "teleport"),
+        match: /unknown execution mode/,
+    },
+    {
+        name: "empty exit predicate",
+        description: CONTRACT_DESCRIPTION.replace("Importing a Planner-authored Linear ticket yields a versioned frozen execution contract.", ""),
+        match: /Exit predicate/,
+    },
+    {
+        name: "duplicate criterion",
+        description: CONTRACT_DESCRIPTION.replace("- [ ] Legacy issues without headings still start", "- [ ] Full ticket imports into the exact structured schema"),
+        match: /duplicate criterion/i,
+    },
+    {
+        name: "empty Evidence line",
+        description: CONTRACT_DESCRIPTION.replace("  Evidence: legacy suite | run the legacy tests | green", "  Evidence:"),
+        match: /Evidence/,
+    },
+    {
+        name: "duplicate heading",
+        description: `${CONTRACT_DESCRIPTION}\n## Non-goals\n- one more\n`,
+        match: /duplicate.*Non-goals/i,
+    },
+    {
+        name: "missing section once a signal is present",
+        description: "## Builder execution mode\nfeature\n\n## Acceptance criteria\n- [ ] Done\n",
+        match: /missing.*Non-goals/i,
+    },
+];
+for (const { name, description, match } of INVALID_DESCRIPTIONS) {
+    test(`POST rejects an invalid contract with an actionable error: ${name}`, async () => {
+        const app = await buildApp();
+        const res = await app.inject({
+            method: "POST",
+            url: "/api/issues",
+            payload: { title: "Bad contract", description, ...BASE_AGENTS },
+        });
+        assert.equal(res.statusCode, 400, `${name}: ${res.body}`);
+        assert.match(res.json().error, match, name);
+        await app.close();
+    });
+}
+test("PATCH validates an edited description and backfills missing criteria", async () => {
+    const app = await buildApp();
+    const created = (await app.inject({
+        method: "POST",
+        url: "/api/issues",
+        payload: { title: "Editable", description: "plain", ...BASE_AGENTS },
+    })).json();
+    // A contract-breaking edit is a 400, not a silent half-parse.
+    const bad = await app.inject({
+        method: "PATCH",
+        url: `/api/issues/${created.id}`,
+        payload: { description: CONTRACT_DESCRIPTION.replace("feature", "teleport") },
+    });
+    assert.equal(bad.statusCode, 400, bad.body);
+    assert.match(bad.json().error, /unknown execution mode/);
+    // Adding the contract fills the missing criteria from the ticket.
+    const good = await app.inject({
+        method: "PATCH",
+        url: `/api/issues/${created.id}`,
+        payload: { description: CONTRACT_DESCRIPTION },
+    });
+    assert.equal(good.statusCode, 200, good.body);
+    const patched = good.json();
+    assert.equal(patched.description, CONTRACT_DESCRIPTION);
+    assert.deepStrictEqual(patched.executionContract, EXPECTED_CONTRACT);
+    assert.ok(patched.acceptanceCriteria.includes("- [ ] Full ticket imports into the exact structured schema"));
+    await app.close();
+});
+test("an active workflow keeps its frozen contract — later edits are refused", async () => {
+    const app = await buildApp();
+    const created = (await app.inject({
+        method: "POST",
+        url: "/api/issues",
+        payload: { title: "Frozen", description: CONTRACT_DESCRIPTION, ...BASE_AGENTS },
+    })).json();
+    assert.equal((await app.inject({ method: "POST", url: `/api/issues/${created.id}/start` })).statusCode, 200);
+    const before = getTaskSnapshot(getIssue(created.id));
+    assert.deepStrictEqual(before.executionContract, EXPECTED_CONTRACT);
+    const refused = await app.inject({
+        method: "PATCH",
+        url: `/api/issues/${created.id}`,
+        payload: { description: CONTRACT_DESCRIPTION.replace("feature", "refactor") },
+    });
+    assert.equal(refused.statusCode, 409);
+    const after = getTaskSnapshot(getIssue(created.id));
+    assert.deepStrictEqual(after, before);
+    await app.close();
+});
+test("NOT-185 + NOT-306: a parked re-freeze updates source and compiled contract atomically", async () => {
+    const app = await buildApp();
+    const created = (await app.inject({
+        method: "POST",
+        url: "/api/issues",
+        payload: {
+            title: "Parked contract",
+            description: CONTRACT_DESCRIPTION,
+            ...BASE_AGENTS,
+            maxReviewRounds: 1,
+        },
+    })).json();
+    assert.equal((await app.inject({ method: "POST", url: `/api/issues/${created.id}/start` })).statusCode, 200);
+    const complete = async (outcome) => {
+        const item = claimWorkItem("route-test", { leaseMs: 60_000 });
+        await applyCompletion(item.id, item.leaseToken, outcome);
+    };
+    const patch = (payload) => app.inject({ method: "PATCH", url: `/api/issues/${created.id}`, payload });
+    await complete({ kind: "clean_handoff", branch: "b", headSha: "abc", baseSha: "base", prNumber: 1, prUrl: "https://gh/pr/1" });
+    await complete({
+        kind: "verdict",
+        result: ReviewerResult.parse({
+            verdict: "changes_requested",
+            baseSha: "b",
+            headSha: "h",
+            acceptanceCriteriaAssessment: "ok",
+            evidenceAssessment: "ok",
+            findings: [],
+            risks: [],
+        }),
+    });
+    // Re-scope the ticket at the park: new exit predicate, one criterion dropped.
+    const rescoped = CONTRACT_DESCRIPTION.replace("Importing a Planner-authored Linear ticket yields a versioned frozen execution contract.", "Importing a Planner-authored Linear ticket yields a versioned frozen execution contract, rescoped.").replace("- [ ] Legacy issues without headings still start\n  Evidence: legacy suite | run the legacy tests | green\n", "");
+    const parked = await patch({ description: rescoped });
+    assert.equal(parked.statusCode, 200, parked.body);
+    const action = listHumanActionsForIssue(created.id).find((a) => a.actionType === "attempts_exhausted");
+    assert.equal(resolveHumanActionAndAdvance(action.id, "operator", "retry").ok, true);
+    // Source and compiled contract re-froze together — never one without the other.
+    const frozen = getTaskSnapshot(getIssue(created.id));
+    assert.equal(frozen.description, rescoped);
+    assert.equal(frozen.executionContract?.exitPredicate, "Importing a Planner-authored Linear ticket yields a versioned frozen execution contract, rescoped.");
+    assert.equal(frozen.executionContract?.acceptanceCriteria.length, 1);
+    assert.deepStrictEqual(getIssue(created.id).executionContract, frozen.executionContract);
+    await app.close();
+});

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

@@ -1,6 +1,6 @@
 // packages/server/src/routes/issues.ts
 import fs from "node:fs";
-import { CreateIssueInput, IssueStatus, UpdateIssueInput, } from "@agent-dealer/shared";
+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";
 import { listWorkerSessionsForIssue, getActiveWorkerSessionForIssue } from "../repository/worker-sessions.js";
@@ -224,7 +224,18 @@ export async function registerIssueRoutes(app) {
                 });
             }
         }
-        const issue = createIssue(input);
+        // NOT-306: an ambiguous/malformed execution contract in the ticket
+        // description is a 400 with an actionable message, never a silent drop.
+        let issue;
+        try {
+            issue = createIssue(input);
+        }
+        catch (err) {
+            if (err instanceof ExecutionContractError) {
+                return reply.status(400).send({ error: err.message });
+            }
+            throw err;
+        }
         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.
@@ -320,6 +331,12 @@ export async function registerIssueRoutes(app) {
             })();
         }
         catch (err) {
+            // NOT-306: a contract edit that turns ambiguous/malformed is a 400 —
+            // the guard above already answered the 409s (wrong status / active
+            // workflow / parked-field allowlist).
+            if (err instanceof ExecutionContractError) {
+                return reply.status(400).send({ error: err.message });
+            }
             const code = err.code;
             const message = err instanceof Error ? err.message : String(err);
             if (code === 404)