fix(linear): teach agent to detect save_issue silent no-ops

DEM-9 (2026-05-27) hit a real failure mode: the agent posted "🔗 PR
opened" + "✅ Task completed successfully" and claimed it transitioned
the issue to In Review, but the issue stayed in In Progress. Root
cause: the DEM team's workflow has no In Review state. When
`mcp__linear-server__save_issue` gets a state name that doesn't exist
on the team, it silently returns 200 with the issue body unchanged,
so it looks like the call succeeded.

Update the Linear-channel prompt to tell the agent to:
 - cache `list_issue_statuses` once per task instead of looping;
 - check the cached state names before each transition and pick the
 closest available one if the requested name doesn't exist;
 - verify the response `state.name` matches what was asked, and NOT
 claim success when the state didn't actually move.

Also forbid embedding `uploads.linear.app/...` URLs in `save_comment`
bodies — Linear's CDN signed URLs don't render when re-embedded by a
bot, producing the broken-image icon you saw on the DEM-9 PR comment.
GitHub's image proxy caches the bytes so the same URL works in PRs;
agent should link to the PR instead.

(cherry picked from commit 2fd73a4)

Author: isadeks

agent/src/prompt_builder.py

@@ -162,21 +162,44 @@ def _channel_prompt_addendum(config: TaskConfig) -> str:
         f"This task was submitted from Linear issue{issue_ref}. The Linear MCP "
         "server is loaded. You MUST perform these updates; they are part of "
         "the task contract, not optional:\n\n"
+        "**State transitions — important.** Different Linear teams configure "
+        "different workflow states. Many teams do NOT have an `In Review` "
+        "state at all (e.g. only Backlog/Todo/In Progress/Done). When you "
+        "pass a state name that doesn't exist on the team's workflow, "
+        "`mcp__linear-server__save_issue` silently no-ops — it returns 200 "
+        "with the issue body unchanged, so it LOOKS like it worked but the "
+        "state never moves. To avoid this:\n"
+        "  - Call `mcp__linear-server__list_issue_statuses` once at the start "
+        "of the task and cache the names you got back.\n"
+        "  - Before each transition, check whether the target name is in the "
+        "cached list. If not, pick the closest available state per the "
+        "fallbacks below.\n"
+        "  - After each `save_issue`, look at the returned `state.name` field "
+        "in the response — if it's not what you asked for, the transition "
+        "didn't happen and you should NOT claim it did.\n\n"
+        "**Comment image rendering — important.** Do NOT embed "
+        "`uploads.linear.app/...` URLs in `save_comment` bodies. Linear's CDN "
+        "signed URLs work in the original poster's context but render as a "
+        "broken-image icon when re-embedded in a comment from a different "
+        "author. If you need to reference an image the user attached, link to "
+        "it in the GitHub PR (where GitHub's image proxy caches the bytes) or "
+        "describe it in words. Other URL hosts (imgur, github user-content) "
+        "are fine to embed.\n\n"
         "1. **At start** — call `mcp__linear-server__save_comment` with a short "
         '"🤖 Starting on this issue…" message, then call '
-        "`mcp__linear-server__save_issue` to transition the issue state. Use "
-        "`mcp__linear-server__list_issue_statuses` first if you don't already "
-        "know the state ids; pick the one named `In Progress` (fall back to "
-        "`Todo` if that state doesn't exist). If the issue is already in "
-        "`In Progress` or any later state (`In Review`, `Done`), skip the "
-        "transition. If neither exists, skip — the comment alone is enough. "
-        "Do not invent state names or loop on `list_issue_statuses`.\n"
+        "`mcp__linear-server__list_issue_statuses` once to get the state map, "
+        "then call `mcp__linear-server__save_issue` to transition to "
+        "`In Progress` (fall back to `Todo` if that state doesn't exist). If "
+        "the issue is already in `In Progress` or any later state (`In Review`, "
+        "`Done`), skip the transition. If neither exists, skip — the comment "
+        "alone is enough. Do not invent state names.\n"
         "2. **When you open the PR** — call `mcp__linear-server__save_comment` "
         "with the PR URL, then call `mcp__linear-server__save_issue` to "
-        "transition the issue state to `In Review` (fall back to `In Progress` "
-        "if that state doesn't exist). If neither exists, skip the state "
-        "transition — the PR comment alone is enough. Do not invent state "
-        "names or loop on `list_issue_statuses`.\n\n"
+        "transition to `In Review`. Use the cached state map from step 1. If "
+        "the team has no `In Review` state, fall back to leaving it at "
+        "`In Progress` — DO NOT silently fail by claiming you transitioned "
+        "when the response shows the state didn't change. Acknowledge in the "
+        "PR comment that the team workflow has no In-Review-equivalent.\n\n"
         "**Do NOT post a final 'task completed' or 'task failed' comment.** "
         "The platform fan-out plane (issue #239) posts a structured "
         "✅/⚠️/❌ summary on terminal events with cost / turns / duration / "

agent/tests/test_entrypoint.py

@@ -603,3 +603,45 @@ def test_linear_addendum_inlines_issue_id_and_project_id(self):
         # so we surface them directly in the prompt.
         assert "issue-uuid-deadbeef" in prompt
         assert "project-uuid-cafebabe" in prompt
+
+    def test_linear_addendum_warns_save_issue_no_ops_on_unknown_state(self):
+        # Regression-guard: many Linear teams do NOT have an `In Review`
+        # state. When the agent passes a state name that doesn't exist,
+        # save_issue silently no-ops — the response shows the unchanged
+        # state, but the agent claimed success on DEM-9 (2026-05-27).
+        # The prompt must (a) tell the agent to cache list_issue_statuses,
+        # (b) check the cached map before each transition, and (c) verify
+        # the response state.name matches what was asked.
+        config = TaskConfig(
+            repo_url="o/r",
+            task_id="t1",
+            max_turns=10,
+            github_token="ghp_test",
+            aws_region="us-east-1",
+            channel_source="linear",
+            channel_metadata={"linear_issue_id": "i"},
+        )
+        prompt = _build_system_prompt(config, self._setup(), None, "")
+        assert "no-op" in prompt or "no op" in prompt
+        assert "cache" in prompt.lower()
+        # Must explicitly call out post-transition response verification.
+        assert "state.name" in prompt or "returned" in prompt.lower()
+
+    def test_linear_addendum_warns_against_embedding_uploads_linear_app_in_comments(self):
+        # Regression-guard: Linear's CDN signed URLs render fine in the
+        # original poster's context but show a broken-image icon when
+        # re-embedded by the bot in a comment. Hit on DEM-9 2026-05-27.
+        config = TaskConfig(
+            repo_url="o/r",
+            task_id="t1",
+            max_turns=10,
+            github_token="ghp_test",
+            aws_region="us-east-1",
+            channel_source="linear",
+            channel_metadata={"linear_issue_id": "i"},
+        )
+        prompt = _build_system_prompt(config, self._setup(), None, "")
+        assert "uploads.linear.app" in prompt
+        # The phrasing must be a prohibition for save_comment specifically,
+        # not just a passing mention — make sure we're forbidding the embed.
+        assert "Do NOT embed" in prompt or "do not embed" in prompt.lower()