feat(api): scope pull_task / GET /work/next to a specific run_id

[viktor-shcherb]

Goal

Let an agent (Claude Code via the Murmur MCP server) drive a single Murmur run end-to-end without picking up unrelated stale or concurrent work that's also in the queue.

Why

The post-demo workflow on jobseek will let any user request a company be added; each request creates a Murmur run that sits in the queue waiting for an agent. When a user prompts their own Claude session "add Stripe to jobseek", that agent must claim only that run's subtasks. Without a run_id scope, pull_task returns the oldest ready row globally — likely some other user's pending request.

Also unblocks the demo: rehearsals leave stale claims in the queue that are FIFO'd ahead of fresh runs, breaking audience-facing dry-runs.

Scope

1. New SQL CLAIM_BY_RUN_SQL in src/api/agent/sql.ts: same shape as CLAIM_SQL plus AND run_id = ? in the inner SELECT.
2. GET /work/next accepts an optional ?run_id=... query param. When set, uses CLAIM_BY_RUN_SQL; otherwise legacy global FIFO.
3. pull_task MCP tool gets an optional run_id: string arg. Description updated to explain the parameter. Forwards to GET /work/next?run_id=....

Interfaces

• CLAIM_BY_RUN_SQL: string (export from sql.ts)
• app.get("/next", ...) — reads c.req.query("run_id")
• PULL_TASK_INPUT_SHAPE = { run_id: z.string().min(1).optional() }

Verification

• Unit test: GET /work/next with no run_id claims oldest ready row globally (legacy).
• Unit test: GET /work/next?run_id=r_X claims oldest ready row whose run_id == r_X, ignoring older ready rows from other runs.
• Unit test: GET /work/next?run_id=r_unknown returns {ok:true, data:null}.
• MCP test: pull_task with no args still works (legacy).
• MCP test: pull_task({run_id: 'r_X'}) claims only that run's work.
• All 3 existing pull_task / submit_result / task_tool tests in src/mcp/server.test.ts still pass.

Definition of done

• Tests above all green.
• pnpm typecheck && pnpm lint && pnpm test && pnpm grep:all clean.
• PR opened referencing this issue, reviewer APPROVE.
• DESIGN.md §3.3 / §3.4 updated to mention the optional run_id filter.

Out of scope

• Listing runs or filtering by initial_input (separate issue).
• Per-user ownership / authz on run access (post-demo).

[viktor-shcherb]

Claimed by developer-agent until 2026-04-30T13:51:48Z.

[viktor-shcherb]

Implementation sketch

Approach: Add a run-scoped variant of CLAIM_SQL (CLAIM_BY_RUN_SQL) that adds AND run_id = ? to the inner SELECT. GET /work/next reads c.req.query("run_id") and routes to the new prepared statement when set; otherwise it keeps the existing legacy global-FIFO claim. The pull_task MCP tool gets an optional run_id: z.string().min(1).optional() arg and forwards it as a query param via in-process agentApp.request("/next?run_id=..."). Description string updated to explain the new parameter. Diffs are minimal: 3 files touched, no schema migration, no API rename, fully backwards compatible.

Files to add/edit:

• src/api/agent/sql.ts — add CLAIM_BY_RUN_SQL export (4-bind variant of CLAIM_SQL)
• src/api/agent/work.ts — import + prepare claimByRunStmt; in GET /next read c.req.query("run_id") and dispatch to the appropriate statement
• src/mcp/tools.ts — add PULL_TASK_INPUT_SHAPE = { run_id?: string }, register pull_task with inputSchema, update PULL_TASK_DESCRIPTION to mention the param, forward via ?run_id= query param to the agent app
• src/api/agent/agent.test.ts — add 3 unit tests (no run_id legacy, with run_id scoped, unknown run_id → null)
• src/mcp/server.test.ts — add pull_task({run_id}) claims-only-that-run test; keep existing 11 tests green

Key types/interfaces:

• export const CLAIM_BY_RUN_SQL: string — bound params: (claim_token, expires_at, updated_at, run_id)
• export const PULL_TASK_INPUT_SHAPE = { run_id: z.string().min(1).optional() }
• pull_task handler signature changes from (extra) => … to (args, extra) => … (the SDK's ToolCallback is discriminated by whether inputSchema is present)

Risks / unknowns:

• The existing pull_task registration omits inputSchema so its handler signature is (extra) => …. Adding inputSchema switches it to (args, extra) => …. The 11 existing tests in src/mcp/server.test.ts invoke pull_task with no arguments; the SDK should pass args = {} (or undefined for optional-only schemas). Per the user's heads-up, the in-process test SDK has a quirk where the callback may receive (extra) instead of (args, extra) — handle both signatures defensively in the handler, and verify by running pnpm test:unit src/mcp/server.test.ts repeatedly.
• The tools/list schema test in server.test.ts asserts pullSchema.required ?? [] is []. Since run_id is optional, this should still pass, but the properties slot will now include run_id. The existing test only asserts required is empty; no change needed.
• The grep gate grep-no-accepted-key scans the codebase — the new description text avoids the literal accepted key.

Test list (from the issue's Verification):

• GET /work/next with no run_id claims oldest ready row globally (legacy)
• GET /work/next?run_id=r_X claims oldest ready row whose run_id == r_X, ignoring older ready rows from other runs
• GET /work/next?run_id=r_unknown returns {ok:true, data:null}
• MCP test: pull_task with no args still works (legacy)
• MCP test: pull_task({run_id: 'r_X'}) claims only that run's work
• All 3 existing pull_task / submit_result / task_tool tests in src/mcp/server.test.ts still pass

DESIGN.md §3.3/§3.4 update is in scope per "Definition of done".

[viktor-shcherb]

Implementation complete, PR #79, ready for review.