fix(agent-ux): atomic claim --next --start, disclosed intent limit overrides, leaner list/search envelopes, MCP flat read parameters

Merged
UN
1d ago
+1697-239

Summary

Four agent-UX defects from today's reports, fixed together because they all come down to agents getting the wrong answer from the CLI or MCP surfaces without being told.

ItemIssueChange
pm-gh1643Closes #1643pm claim --next --start is one atomic write on CLI, MCP and SDK; claim-target refusals are typed and never ask for a flag the caller already passed
pm-gh1644Closes #1644A --for intent that reduces an explicit --limit now says so (receipt, warning, filters.requested_limit, restore_with); the quickstart recommends the measured canonical pm context --for orient
pm-gh1642Closes #1642Leaner brief TOON envelopes for pm list and pm search
pm-hke9z7— (found while verifying GH-1644 over MCP)MCP read tools now read every declared flat parameter; pm_search honours its declared keywords alias

Details

GH-1643: atomic select-claim-start. Any --start used to go to the explicit-id target check, which ignored --next and answered "pass --next". MCP failed the same way. runClaim now accepts start and advances the item to the configured in-progress status inside the claim's own mutateItem callback, using the same pattern release --handoff uses. That gives one write and one claim history event, with type-workflow enforcement, terminal_state_conflict for terminal items, and a start { from_status, to_status } receipt. claim --next forwards start through its race-loss walk, so filters, --max-attempts and --if-available are unchanged. Explicit claim <id> --start keeps its documented claim-then-update composition and its typed refusal (an existing integration test pins both). PmClient.claimNext({ start: true }) is typed. The MCP schema no longer forbids start + next.

GH-1644: disclosed intent limits. The orient budget really does carry 3 rows: 10 rows measure ~5,900 JSON tokens on this 3,173-item tracker. So the ceiling stays, and only the silence is fixed. pm context --for orient --limit 10 now reports:

filters: { limit: "3", requested_limit: "10" }
warnings: ["limit_overridden_by_intent:--limit 10->3"]
context_intent.limit_override: { requested: 10, effective: 3, token_budget_for_requested: 7200,
  restore_with: "--token-budget 7200" }

restore_with is a flag to add to the original command, like an omission receipt's restore_with: "--full", so every positional, inline filter and option is kept. Adding it returns 10 rows at 4,637 estimated tokens within budget. list --for triage and search --for discover behave the same way. The replayed agent-task transcripts moved to the canonical form; the token baseline changed only its digest, because the output is identical.

GH-1642: envelopes. Measured against the published 2026.10.31 package on this tracker:

CommandBeforeAfter
pm search "release workflow" --limit 31,033 B863 B (−16%)
pm list --status open --limit 3988 B782 B (−21%)

Two fields are kept on purpose:

  • completeness: unchecked stays, because the #1501 contract says unchecked source evidence must not disappear.
  • items_encoding stays, because it is the lossless decode contract for the matched_fields list column.

The default sort keeps its effective comparator order: the #1507 contract and its integration spec require that disclosure. It is now one line instead of seven. JSON, --full and SDK results are unchanged.

Review round 1 (CodeRabbit). Fixes applied:

  • Start now enters a configured custom in-progress status. This bug predated the PR and affected both explicit and ranked starts.
  • The compact receipt keeps start.
  • A post-commit attribution failure is now a warning, not an error.
  • restore_with is a flag fragment, omitted for unsafe budgets.
  • The list filters echo fix is complete.
  • The docs state that pm_search's query stays top-level.

Starting an item with an open blocker matches update semantics and is filed as pm-urzubi.

pm-hke9z7: MCP flat parameters. Flat-to-options hoisting was a hand list. pm_context had no entry at all, and for/tokenBudget/depth never reached pm_list, pm_search, pm_next or pm_get. Hoisting for these five read actions is now derived from PM_TOOL_ACTION_PARAMETER_CONTRACTS, and nested options still win. A regression spec iterates every declared optional key.

Verification

  • Full fast suite run locally; failures traced to this change were fixed (guidance literals, help-token ratchet, surface snapshot, MCP hoist expectations, the #1507 sort disclosure).
  • Full-source coverage run at 100%.
  • Negative controls with the fix stashed: GH-1643 CLI/MCP start test fails; GH-1644 3/3 fail; GH-1642 cases fail; pm-hke9z7 6/7 fail.
  • Static gates green locally: static-quality (complexity, docstrings, SDK import boundary), lint, duplicates, contracts, error-code catalog, SDK surface (optional additions acknowledged), surface replication (two CLI refusals moved into the SDK), command grammar, flag parity/lexicon, refusal closure, agent-task tokens, MCP deprecations, gate registry, entrypoint costs, transport floor, and the tracker-context-quality/graph-composition/record-integrity assurances. The dependency advisory gate cannot reach OSV from this workstation; CI runs it.

Also in this PR: #1641 (nightly quality) is closed with its root cause (the advisories fixed in #1638), and the release-health checkpoint is recorded on pm-7zs0.

Summary by Sourcery

Improve agent-facing CLI and MCP reliability by making ranked starts atomic, disclosing read-limit overrides, reducing brief output, and honoring declared read parameters.

New Features:

  • Support atomic claim --next --start across the CLI, MCP, and SDK with typed results and actionable refusals.
  • Expose intent-driven limit reductions and safe restoration guidance across context, list, and search reads.
  • Support all declared flat MCP read parameters and the pm_search keywords alias.

Bug Fixes:

  • Preserve dependency relationships when filtered context results are generated.
  • Treat post-commit claim attribution failures as warnings without failing persisted claims.

Enhancements:

  • Compact brief TOON envelopes for list and search while preserving completeness, effective sorting, and lossless row decoding.

Documentation:

  • Update agent quickstarts and lifecycle documentation for atomic ranked starts and the canonical orientation command.

Tests:

  • Add coverage for atomic claim/start behavior, intent-limit disclosures, compact envelopes, MCP parameter handling, and filtered dependency edges.

Chores:

  • Record issue, history, and release-health tracking updates for the related fixes.