docs(tasks): tighten rerun trigger surface; clean stale Go comments

Apply review feedback on PR #2304:

- `tasks.mdx` / `tasks.zh.mdx`: rerun is triggered via CLI or the
  `/api/issues/{id}/rerun` endpoint, not "UI or CLI" — there's no rerun
  affordance in web/desktop today.
- `tasks.mdx` / `tasks.zh.mdx`: comparison table — manual rerun applies
  to "Issues with an agent assignee", not "All sources". The handler
  rejects with `issue is not assigned to an agent` for anything else,
  and there's no rerun path for chat or autopilot tasks.
- `task_lifecycle.go`: `RerunIssue` doc comment claimed the new task
  "carries the most recent session_id/work_dir so the agent can resume".
  That has been false since b1345685 — rewrite to reflect the actual
  `force_fresh_session=true` contract.
- `agent.sql` (regenerated `agent.sql.go`): `GetLastTaskSession` doc
  said it serves "auto-retry / manual rerun"; manual rerun is now
  routed around it via `force_fresh_session=true`. Note both the
  auto-retry path it does serve and the rerun escape hatch.

No logic change.

Co-authored-by: multica-agent <github@multica.ai>

apps/docs/content/docs/cli.mdx

@@ -54,7 +54,7 @@ For the difference between token types, see [Authentication and tokens](/auth-to
 | `multica issue status <id> --set <status>` | Shortcut to change status |
 | `multica issue search <query>` | Keyword search |
 | `multica issue runs <id>` | Show agent runs on an issue |
-| `multica issue rerun <id>` | Rerun the most recent agent task |
+| `multica issue rerun <id>` | Re-enqueue a fresh task for the issue's current agent assignee |
 | `multica issue comment <id> ...` | Nested: view / post comments |
 | `multica issue subscriber <id> ...` | Nested: subscribe / unsubscribe |
 | `multica project list/get/create/update/delete/status` | Project CRUD |

apps/docs/content/docs/cli.zh.mdx

@@ -54,7 +54,7 @@ Token 类型的详细区分见 [认证与令牌](/auth-tokens)。
 | `multica issue status <id> --set <status>` | 快捷改状态 |
 | `multica issue search <query>` | 关键字搜索 |
 | `multica issue runs <id>` | 查看 issue 上智能体跑过的任务 |
-| `multica issue rerun <id>` | 重跑最近一次智能体任务 |
+| `multica issue rerun <id>` | 给该 issue 当前的智能体分配人重新创建一条任务 |
 | `multica issue comment <id> ...` | 嵌套：看 / 发评论 |
 | `multica issue subscriber <id> ...` | 嵌套：订阅 / 取消订阅 |
 | `multica project list/get/create/update/delete/status` | Project CRUD |

apps/docs/content/docs/tasks.mdx

@@ -69,7 +69,7 @@ Automatic retry also has two extra conditions:
 
 ## Manual rerun vs. automatic retry
 
-A **manual rerun** is one you trigger from the UI or CLI:
+A **manual rerun** is one you trigger from the CLI or the API (`POST /api/issues/{id}/rerun`):
 
 ```bash
 multica issue rerun <issue-id>
@@ -77,9 +77,10 @@ multica issue rerun <issue-id>
 
 Behavior:
 
-- **Cancels** the currently running task (if any)
-- Creates a **brand-new** task — attempt count resets to 1, even if the original task hit the attempt ceiling
-- Inherits the previous session ID; if the corresponding AI coding tool supports session resumption, the new task continues from the previous context
+- Targets the issue's **current agent assignee** — not whoever ran the most recent task. If the assignee changed since the last run, rerun follows the current assignment. To rerun a specific agent that is no longer the assignee, reassign the issue first, then rerun.
+- **Cancels** the assignee's queued or running task on this issue (if any). Tasks owned by other agents on the same issue (e.g. parallel @-mention runs) are left alone.
+- Creates a **brand-new** task — attempt count resets to 1, even if the original task hit the attempt ceiling.
+- Starts a **fresh agent session** — the prior session ID is **not** inherited. A manual rerun means you've judged the previous output bad, so resuming the same conversation would replay the same poisoned state. (Automatic retry, by contrast, does inherit the session — that path is for infrastructure failures, not bad output.)
 
 Comparison:
 
@@ -87,8 +88,9 @@ Comparison:
 |---|---|---|
 | Trigger | System, based on failure reason | You, manually |
 | Ceiling | 2 attempts | No limit |
-| Applicable sources | Issues, chat | All sources |
-| Session inheritance | Yes | Yes |
+| Applicable sources | Issues, chat | Issues with an agent assignee |
+| Agent picked | Same agent as the failed task | Issue's current assignee |
+| Session inheritance | Yes (resumes prior session) | No (fresh session) |
 
 ## How a failed task affects issue status
 
@@ -98,7 +100,7 @@ If an issue-triggered task fails (and no automatic retry succeeds) because the i
 
 Yes — as long as the AI coding tool supports session resumption.
 
-Multica pins the session ID **twice** during a task: once at the start (when the AI tool returns its first system message), and once at the end (on completion or failure). The first lets the daemon recover if it crashes mid-run; the second is reserved for future reruns. On the next rerun or automatic retry, that ID is passed back so the agent can pick up the previous conversation and file state.
+Multica pins the session ID **twice** during a task: once at the start (when the AI tool returns its first system message), and once at the end (on completion or failure). The first lets the daemon recover if it crashes mid-run; the second is reserved for the next **automatic retry**, where that ID is passed back so the agent can pick up the previous conversation and file state. **Manual rerun deliberately skips this** and starts a fresh session — see [Manual rerun vs. automatic retry](#manual-rerun-vs-automatic-retry).
 
 But **which AI coding tools actually support this** varies a lot:
 

apps/docs/content/docs/tasks.zh.mdx

@@ -69,7 +69,7 @@ Multica 服务器每 30 秒扫描一次，有两种超时会触发失败：
 
 ## 手动重跑和自动重试的区别
 
-**手动重跑**（rerun）是你从 UI 或命令行主动发起的：
+**手动重跑**（rerun）是你通过命令行或 API（`POST /api/issues/{id}/rerun`）主动发起的：
 
 ```bash
 multica issue rerun <issue-id>
@@ -77,9 +77,10 @@ multica issue rerun <issue-id>
 
 行为：
 
-- **取消**当前正在跑的任务（如果有）
-- 创建一个**全新**的执行任务——尝试次数重置为 1，即使原任务已达最大尝试
-- 继承上一次的会话 ID；如果对应的 AI 编程工具支持会话恢复，会接着上次的上下文继续
+- 跑的是 issue **当前的智能体分配人**——不是上一次跑过的 agent。如果分配人在上次运行后改了，rerun 会跟着新的分配人走。要重跑一个已经不再是分配人的智能体，先把 issue 改派回它，再 rerun。
+- **取消**该分配人在这条 issue 上 queued / running 的任务（如果有）。同 issue 上其它 agent 的任务（例如 @-mention 触发的并行任务）不会被一起取消。
+- 创建一个**全新**的执行任务——尝试次数重置为 1，即使原任务已达最大尝试。
+- 启动**全新的智能体会话**——**不**继承之前的会话 ID。手动重跑意味着你已经判定上一次的产出不行，再继续之前的对话只会重放被污染的上下文。（自动重试则相反，会继承会话——那条路径处理的是基础设施层面的失败，不是产出不好。）
 
 对比：
 
@@ -87,8 +88,9 @@ multica issue rerun <issue-id>
 |---|---|---|
 | 触发 | 系统基于失败原因自动执行 | 你主动发起 |
 | 上限 | 2 次 | 无上限 |
-| 适用来源 | issue、聊天 | 所有来源 |
-| 会话继承 | 是 | 是 |
+| 适用来源 | issue、聊天 | 有智能体分配人的 issue |
+| 跑哪个 agent | 失败任务原本的 agent | issue 当前的分配人 |
+| 会话继承 | 是（接着上次会话） | 否（全新会话） |
 
 ## 失败的任务对 issue 状态有什么影响
 
@@ -98,7 +100,7 @@ multica issue rerun <issue-id>
 
 可以——前提是对应的 AI 编程工具支持会话恢复。
 
-Multica 在任务过程中**两次**保存会话 ID——任务一开始（AI 工具返回第一条系统消息时）pin 一次，任务结束（完成或失败）时再 pin 一次。前者让守护进程中途崩溃时也能恢复，后者给之后的重跑用。下次重跑或自动重试时把这个 ID 传回去，智能体就能接着上次的对话、文件状态继续。
+Multica 在任务过程中**两次**保存会话 ID——任务一开始（AI 工具返回第一条系统消息时）pin 一次，任务结束（完成或失败）时再 pin 一次。前者让守护进程中途崩溃时也能恢复，后者留给下一次**自动重试**——届时把这个 ID 传回去，智能体就能接着上次的对话和文件状态继续。**手动重跑会主动跳过这一步**，永远从全新会话开始——见 [手动重跑和自动重试的区别](#手动重跑和自动重试的区别)。
 
 但**哪些 AI 编程工具真的支持**差别很大：
 

server/internal/handler/task_lifecycle.go

@@ -96,8 +96,12 @@ func (h *Handler) PinTaskSession(w http.ResponseWriter, r *http.Request) {
 
 // RerunIssue manually re-enqueues the issue's current agent assignment as a
 // fresh task. Useful when an issue is stuck or the user wants to retry a
-// failed run. The new task carries the most recent session_id/work_dir so
-// the agent can resume where it left off when the backend supports it.
+// failed run. The new task is flagged force_fresh_session=true: the daemon
+// claim handler skips the (agent_id, issue_id) session-resume lookup so the
+// agent starts a clean session. A user clicking rerun has just judged the
+// prior output bad — replaying the same conversation would replay the same
+// poisoned state. (Automatic retry, by contrast, intentionally inherits the
+// session — that path handles infrastructure failures, not bad output.)
 func (h *Handler) RerunIssue(w http.ResponseWriter, r *http.Request) {
 	id := chi.URLParam(r, "id")
 	issue, ok := h.loadIssueForUser(w, r, id)

server/pkg/db/generated/agent.sql.go

@@ -1052,18 +1052,24 @@ type GetLastTaskSessionRow struct {
 }
 
 // Returns the session_id and work_dir from the most recent task for a given
-// (agent_id, issue_id) pair, used for session resumption. We accept both
-// 'completed' and 'failed' tasks: a failed task may have established a real
-// agent session before crashing (orphaned by a daemon restart, runtime offline,
-// or sweeper timeout), and the daemon pins the resume pointer mid-flight via
-// UpdateAgentTaskSession. Without this, an auto-retry / manual rerun of a
-// mid-run failure would silently start a fresh conversation and lose the
-// in-flight context — exactly what MUL-1128's B branch is meant to fix.
+// (agent_id, issue_id) pair, used for session resumption on the auto-retry
+// path. We accept both 'completed' and 'failed' tasks: a failed task may
+// have established a real agent session before crashing (orphaned by a
+// daemon restart, runtime offline, or sweeper timeout), and the daemon pins
+// the resume pointer mid-flight via UpdateAgentTaskSession. Without this,
+// an auto-retry of a mid-run failure would silently start a fresh
+// conversation and lose the in-flight context — exactly what MUL-1128's B
+// branch is meant to fix.
 //
-// Tasks that ended in a known "poisoned" terminal state are excluded so
-// a rerun does not inherit the bad session. The daemon classifies these
-// failures (iteration_limit, agent_fallback_message) when it detects the
-// agent emitted a fallback marker instead of a real result.
+// Manual rerun (TaskService.RerunIssue) does NOT take this path: it sets
+// force_fresh_session=true on the new task, and the daemon claim handler
+// skips this lookup entirely. The user already judged the prior output bad;
+// resuming the same conversation would replay a poisoned state.
+//
+// Tasks that ended in a known "poisoned" terminal state are also excluded
+// here so even auto-retry does not inherit the bad session. The daemon
+// classifies these failures (iteration_limit, agent_fallback_message) when
+// it detects the agent emitted a fallback marker instead of a real result.
 func (q *Queries) GetLastTaskSession(ctx context.Context, arg GetLastTaskSessionParams) (GetLastTaskSessionRow, error) {
 	row := q.db.QueryRow(ctx, getLastTaskSession, arg.AgentID, arg.IssueID)
 	var i GetLastTaskSessionRow

server/pkg/db/queries/agent.sql

@@ -224,18 +224,24 @@ RETURNING *;
 
 -- name: GetLastTaskSession :one
 -- Returns the session_id and work_dir from the most recent task for a given
--- (agent_id, issue_id) pair, used for session resumption. We accept both
--- 'completed' and 'failed' tasks: a failed task may have established a real
--- agent session before crashing (orphaned by a daemon restart, runtime offline,
--- or sweeper timeout), and the daemon pins the resume pointer mid-flight via
--- UpdateAgentTaskSession. Without this, an auto-retry / manual rerun of a
--- mid-run failure would silently start a fresh conversation and lose the
--- in-flight context — exactly what MUL-1128's B branch is meant to fix.
+-- (agent_id, issue_id) pair, used for session resumption on the auto-retry
+-- path. We accept both 'completed' and 'failed' tasks: a failed task may
+-- have established a real agent session before crashing (orphaned by a
+-- daemon restart, runtime offline, or sweeper timeout), and the daemon pins
+-- the resume pointer mid-flight via UpdateAgentTaskSession. Without this,
+-- an auto-retry of a mid-run failure would silently start a fresh
+-- conversation and lose the in-flight context — exactly what MUL-1128's B
+-- branch is meant to fix.
 --
--- Tasks that ended in a known "poisoned" terminal state are excluded so
--- a rerun does not inherit the bad session. The daemon classifies these
--- failures (iteration_limit, agent_fallback_message) when it detects the
--- agent emitted a fallback marker instead of a real result.
+-- Manual rerun (TaskService.RerunIssue) does NOT take this path: it sets
+-- force_fresh_session=true on the new task, and the daemon claim handler
+-- skips this lookup entirely. The user already judged the prior output bad;
+-- resuming the same conversation would replay a poisoned state.
+--
+-- Tasks that ended in a known "poisoned" terminal state are also excluded
+-- here so even auto-retry does not inherit the bad session. The daemon
+-- classifies these failures (iteration_limit, agent_fallback_message) when
+-- it detects the agent emitted a fallback marker instead of a real result.
 SELECT session_id, work_dir, runtime_id FROM agent_task_queue
 WHERE agent_id = $1 AND issue_id = $2
   AND (