# Reported issues for MCP Task Orchestrator Pod holds 17 of 20 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user. Back to [MCP Task Orchestrator](/mcp/mcp-task-orchestrator). ## Most discussed ### feat: Atomic work item claim mechanism for multi-agent environments ## Problem When multiple independent agents connect to a single Task Orchestrator instance and call `get_next_item` concurrently, they receive identical recommendations. There is no exclusivity mechanism -- two agents can both receive the same QUEUE item, and only the first to call `advance_item(trigger="start")` succeeds. The second agent discovers the conflict via optimistic locking (`ConflictError` from version mismatch), but only **after** it has already committed to working on that item. [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/117) · 2026-04-16 · closed · 12 comments ### JWKS-based ActorVerifier implementation (Stage 2 actor attribution) ## Summary Implement a concrete `ActorVerifier` that validates actor claims against JWKS keys. Stage 1 (#101, PR #105, PR #106) landed the schema, `NoOpActorVerifier`, config-driven enforcement (`auditing.enabled`), and query surfacing. This issue implements the verification half — turning `unverified` claims into `verified` or `failed`. ## Background The `ActorVerifier` interface and `proof` field were designed for this: ```kotlin interface ActorVerifier { suspend fun verify(actor: Acto [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/107) · 2026-04-14 · closed · 5 comments ### feat: Native DID document support for actor verification ## Problem Our `JwksActorVerifier` (introduced in #107, hardened in #120, integrated with claims in #117) accepts public keys from three sources: an OIDC discovery document, a direct JWKS URI, or a local JWKS file. All three paths converge on `JWKSet.parse(body)` — i.e., the bytes must already be a JWKS envelope (`{ "keys": [...] }`). A **DID document** is structurally different. Public keys live nested under `verificationMethod[].publicKeyJwk` (or `publicKeyMultibase`), wrapped in a W3C-defin [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/156) · 2026-04-30 · closed · 3 comments ### Resource leasing: model shared credentials a work item consumes, not just notes an agent writes ## Background In discussion #97, a commenter [asked](https://github.com/jpicklyk/task-orchestrator/discussions/97#discussioncomment-17774297) whether the trait system has room for *a resource a work item consumes*, as opposed to *a note the agent must write*. The motivating failure mode: multiple agent instances, each with a distinct internal identity, all present to external services as the **same credential** (same GitHub token, same deploy key). Per-agent attribution answers "which agent did [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/261) · 2026-07-25 · closed · 2 comments ### Sub-agents colliding on same tasks despite existing protection mechanisms ## Problem Description When attempting to parallelize multiple sub-agents to take a feature and start implementing all tasks under it, the sub-agents are taking the same feature and task instead of distributing the work. This occurs despite having comprehensive protection mechanisms built into the system. ## Root Cause Analysis After investigating the codebase, the issue is that the locking protection mechanisms exist but are **not actively being used** by the MCP tools: ### 🔍 **What's Built [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/5) · 2025-06-26 · closed · 2 comments ### [proposal] Spec-quality: measure automated budget/ceiling headroom during planning ## Problem When a change touches a surface guarded by an automated budget/ceiling test (e.g. a tools-list token budget), discovering the constraint during implementation is materially worse than during planning — the scope decision has already been made and dispatched. Observed twice: one rejection-and-rework after the guard fired post-implementation, and one planning-time measurement that changed the design (headroom of 1–8 chars on several tools narrowed a 16-tool sweep to 8 tools and halved [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/281) · 2026-07-31 · closed · 1 comment ### [proposal] Spec-quality: prove verification commands with a positive run AND a negative control ## Problem Verification commands get written into plans, specs, and skills and then trusted without ever being run. Three failure mechanisms observed: (1) command doesn't run on the target platform; (2) command runs but verifies nothing (a "YAML validity check" that passes on any readable file); (3) command runs but silently returns everything (a drift-check whose range pattern never terminated, so it always dumped the whole file and the drift it existed to catch went undetected across several [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/280) · 2026-07-31 · closed · 1 comment ### [proposal] Implement workflow: non-blocking post-dispatch commit audit before squash-merge ## Problem Implementation subagents have committed to feature branches despite explicit "do not run git" dispatch instructions — three occurrences across two sessions, including one where the instruction explicitly superseded the default commit convention at maximal explicitness. All three commits were clean and correctly scoped, but the orchestrator only discovered them after the fact. Wording escalation alone has failed twice. ## Proposed change Add a cheap, non-blocking post-dispatch commi [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/278) · 2026-07-31 · closed · 1 comment ## Most recent ### [proposal] Guard against declared-but-never-read tool parameters ## Problem A parameter declared in a tool's `parameterSchema` but never read on some operation's code path is accepted, silently ignored, and reported as **success**. Confirmed live on 2026-08-04: ``` manage_items(operation="update", items=[{itemId}], traits: "delegated,needs-task-review") → {"updated": 1, "failed": 0} ← merged nothing ``` `ManageItemsTool`'s update branch never read the top-level `traits` param; the create branch always had. Because the same parameter **does** work on ` [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/290) · 2026-08-04 · open · 0 comments ### [proposal] Closeout convention: closure notes in confirmed past tense, written after merge-check and advance ## Problem Closure notes (session-tracking / resolution) drafted before the merge+advance happen read "in review, awaiting merge — complete after merge" forever, even after the item is terminal and the PR merged. Two same-day retrospectives found terminal items with self-contradicting closure records, degrading the audit trail retrospectives depend on. ## Proposed change Closeout-sequencing convention: finalize a closure note as the LAST step — merge-check (`git merge-base --is-ancestor` / PR [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/277) · 2026-07-31 · closed · 1 comment ### [proposal] Review guidance: direct existence-check before asserting a file/artifact is missing ## Problem Review agents occasionally assert a negative claim ("file X is missing", "this will throw") without a direct verification step. Two observed instances: a reviewer pattern-matched a prior serialization bug onto an unrelated, actually-safe type; another declared a skill file missing after checking only one of the two skill directories (plugin `skills/` vs project `.claude/skills/`). Both were caught downstream, costing verification cycles. ## Proposed change Add one checklist line to [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/276) · 2026-07-31 · closed · 1 comment ### [proposal] advance_item: singular-form validation hint + gate-block errors naming the blocked transition ## Problem `advance_item`'s transition semantics repeatedly confuse callers. Evidence across multiple sessions: (1) callers using a singular `itemId`+`trigger` form get a generic `Missing required parameter: transitions` that doesn't name the expected batch shape; (2) gate-block errors don't say **which** transition (previousRole→targetRole) was gated, which has been misread as timing-dependent behavior — the gate is actually a deterministic function of the current phase, so successive `start` [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/275) · 2026-07-31 · closed · 1 comment ### feat: align VerificationStatus enum to industry patterns ## Background The current `VerificationStatus` enum has three values: ```kotlin enum class VerificationStatus { UNVERIFIED, // Proof absent or noop verifier VERIFIED, // All checks passed FAILED // Something went wrong } ``` As the verification layer gains more consumers — audit logging, the claim mechanism (#117), future trust-gating, observability — two structural gaps become increasingly expensive to leave unaddressed. --- ## Gap 1 — `UNVERIFIED` conflates two disti [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/121) · 2026-04-19 · closed · 0 comments ### feat: JWKS stale-cache fallback and verification result metadata ## Background `DefaultJwksKeySetProvider` already implements an in-memory TTL cache (configurable via `cache_ttl_seconds`, default 300s) with mutex-protected refresh. The basic caching story is solid. The gap is **stale-on-error fallback behavior**: when the cache TTL has expired and the JWKS endpoint is temporarily unreachable, the current implementation propagates the network error up to `JwksActorVerifier`, which returns `VerificationResult(status=FAILED)`. From the caller's perspective, a [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/120) · 2026-04-19 · closed · 0 comments ### Generic actor attribution on transitions and notes (ActorVerifier seam) ## Summary Task history records *what* changed but not *who* changed it. In multi-agent orchestration (the dispatch pattern this project itself uses), transitions and notes are indistinguishable across the orchestrator, materialization agents, implementation agents, and review agents. Post-mortems have to infer authorship from prose. ## Problem Three concrete gaps: 1. `advance_item` persists transitions with no actor field — history shows the status change, not the caller. 2. `manage_notes(u [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/101) · 2026-04-11 · closed · 0 comments ### Composable traits — agent-assigned note requirement composition ## Summary Add a `traits` field to WorkItem that allows agents to compose additional note requirements per-item at creation time. Traits are additive — they merge with the base type schema's notes. ## Motivation Different items of the same type may need different documentation requirements based on context. A feature touching auth needs a security review note; a performance-sensitive feature needs a performance baseline note. Rather than defining every combination as a separate type (`feature [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/91) · 2026-04-01 · closed · 0 comments ### Suggest redirecting logs from stdout to stderr to comply with MCP protocol specification Body: Hi, thank you for developing task-orchestrator! While using it, I encountered a compatibility issue related to the MCP protocol, and I’d like to suggest a small improvement. Problem description task-orchestrator, as an MCP server, writes logs (INFO, DEBUG, etc.) to stdout by default. However, according to the MCP protocol specification, a server’s stdout must be used exclusively for JSON‑RPC messages. Any output that is not a valid JSON‑RPC message will cause the client to fail parsing. [Read the thread](https://github.com/jpicklyk/task-orchestrator/issues/84) · 2026-03-23 · closed · external user · 1 comment The remaining reports are on [the project's issue tracker](https://github.com/jpicklyk/task-orchestrator.git/issues).