9 Commits

Author	SHA1	Message	Date
xarmian	449ac109e9	fix(server,mcp,cli): refuse system-metadata keys in fields_patch + retry-hostile error code (BUG-2627 part 2, BUG-2675) (#1166) ... * fix(server,mcp,cli): refuse system-metadata keys in fields_patch + retry-hostile error code (BUG-2627 part 2, BUG-2675) Part 2 of BUG-2627 closes the door that mints the defect parts 1 and 3 dealt with: `--field implementation_notes=<json>` stored the entries as a JSON-ENCODED STRING, which is invisible to every reader and — since part 3's guard — disables `pad item note` on that item until the row is repaired. Refused SERVER-SIDE in `fields_patch`, not at the CLI as the item's scope line proposed. The deviation is deliberate and recorded on the trail: the CLI is one of three clients, and all three lower a user field-setter into the same key (`pad item update --field` at cmd_item.go, the MCP `field` param via dispatch_http_advanced.go on remote, and stdio by shelling out to that CLI). One gate closes all three; a CLI-only refusal would have left remote MCP writing the key. Both call sites were read, and the CLI's lowering is now pinned by a test rather than left as an assumption. Scope, stated because it is deliberate: this closes UPDATE only. The full `fields` blob stays open because that door is SHARED — `pad item note` / `decide` / `github link` send one, and so does convention activation via BuildConventionItemFields -> ItemCreate. Closing it would break the system writers the gate exists to protect. Item create therefore remains a mint site, tracked with the rest of that surface in BUG-2685. The refusal message is per-key: implementation_notes -> `pad item note`, decision_log -> `pad item decide`, github_pr -> the GitHub link flow, and `convention` refuses WITHOUT naming a command, because none writes it. PATTE-135 wants a remedy that works in the failing state; a single "use pad item note" line would have been wrong for three of the four keys. BUG-2675 rides along on one ToolSurfaceVersion bump, as ruled. The append refusal from part 3 reached MCP agents as `server_error` — not our fault, and not transient, so agents could reasonably retry a failure that is deterministic forever. New closed-set code `stored_state_unreadable`, emitted on BOTH transports: HTTP classifies the sentinel error directly, stdio via a `pad-structured-error/v1:` marker the CLI now writes for its own local refusal (the first marker generated without an upstream APIError). v0.16-then-v0.17 is what a one-transport fix costs. Also here: - items.ReservedOverrideKeys -> ReservedFieldKeysIn. The second caller passes a patch, not an override map, and the old doc comment said fields_patch was an open exposure — true until this commit. - `Extract* returns nil for THREE reasons` -> FOUR. The comment listed four; the count was corrected everywhere except the code. - Consumer-read artifacts updated where the claim is ACTED on, not only where it is documented: instructions.md (incl. a "do not retry this code" section), the catalog `field` param description, `pad item update --help`, README. Gates: build · make lint · go test ./... · make test-pg · Codex. Eleven-mutation matrix run against the new tests; every one killed by an assertion (two were rewritten after killing by compile error / surviving, which proves nothing). Claude-Session: https://claude.ai/code/session_017jD6t1zjxGSq47SQpZfp1V * fix(server,mcp): honest remedy when the stored value is already unreadable; name the MCP-facing code (Codex round 1) Three findings from the pre-push review, all real: P2 — the refusal named `pad item note` unconditionally, but on an item whose stored value is ALREADY undecodable that command refuses too (part 3's guard). The caller was routed in a circle: field write refused -> run the note -> refused -> back again. That is exactly the failure PATTE-135 exists to prevent, and my own trail had reasoned the remedy was safe on the strength of the HEALTHY case only. The message now inspects the item's stored value and, when the key is unparseable, says so and points at the one action that works in that state (inspection), noting that the repair needs a full `fields` write no CLI flag exposes. P2 — two doc claims were false where an actor reads them. The catalog said reserved keys are refused "on every action that accepts field", which includes CREATE, and create is deliberately NOT gated; and both the catalog and instructions.md named `validation_error` (the HTTP code) where an MCP client actually receives `validation_failed`. Both corrected, and the create exception is now stated rather than implied by omission — an agent that reads only "refused on update" will otherwise assume create is fine, which is how a hole gets used. nit — the destructive-downstream sentence claimed every reserved key becomes unreadable and trips an append guard. True only for the two append-backed keys; github_pr and convention are simply overwritten. The clause is now per-key, because a confident wrong explanation is worse than a vague right one. Two more mutations run against the new branch: always-readable (the circular remedy returns) and never-readable (the working remedy disappears) — both killed by assertions. Claude-Session: https://claude.ai/code/session_017jD6t1zjxGSq47SQpZfp1V * fix(models,mcp,cli): one appendability predicate, per-key docs, stdio hint parity (Codex round 2) Five findings, all real. P2 — the message's readability check and the guard it describes were two different decodes. Mine unmarshalled into []json.RawMessage; the guard uses []ItemImplementationNote. A stored `[1]` passed mine and fails the guard, so the message would again have prescribed a command that refuses — the same circularity round 1 caught, through a narrower door. Replaced with models.StructuredFieldIsAppendable, which ASKS the guard rather than re-deriving it, plus an agreement test over 12 shapes x 2 keys that compares the predicate against the real Append* helpers. Verified by restoring the RawMessage version: the table catches it on `[1]`. P2 — stdio lost the new code's hint. Remote MCP told the agent retrying is pointless and how to inspect; stdio got the code with an empty hint, because the CLI's marker envelope carried none and the classifier parsed none. Both fixed, with the hint hoisted into paired constants (the same duplication StructuredErrorMarker already uses) and the test comparing the two TRANSPORTS' envelopes rather than either against a literal. P2 — doc text was still false for `convention`: the catalog, the instructions and `--help` all said reserved keys are maintained by note/decide/the GitHub flow, which is true of three of the four. Each key now names its own writer, and `convention` names library activation. Also dropped the `malformed_override` advertisement — that is the SERVER's code; an MCP client sees validation_failed for both refusals. nit — the classification test called structuredAppendErrorResult directly, so deleting either dispatcher call site left it green. Added dispatcher-level tests driving the real server + store, asserting the code, the hint, and that the item's stored fields are byte-identical afterwards. Mutation-verified by reverting the note call site. Claude-Session: https://claude.ai/code/session_017jD6t1zjxGSq47SQpZfp1V * fix(items,models,mcp): github_pr stays writable through fields_patch; no nil-map panic (Codex round 3) P1 — the gate refused `github_pr`, and that was wrong. My model was "system writers use the full fields blob, user setters use fields_patch", which holds for three of the four reserved keys and fails for this one: `pad github link` needs a local git checkout and the `gh` CLI, so it is excluded from remote MCP BY NAME, and internal/mcp/dispatch_http.go's noRemoteEquivalent map tells remote agents in so many words to use `item update --field github_pr=...` instead. For that audience the patch door is not a bypass of the writer — it IS the writer. So the refusal deleted a documented capability from remote agents, and answered with a message naming a command they cannot run: the same circular remedy round 1 caught, aimed this time at the people the gate was meant to help. items.PatchRefusedFieldKeysIn now exempts the key and records the rule being applied — refuse a raw write where a real writer exists — rather than the list it produces. Whether remote agents should get a proper PR-link action, so the key can be closed too, is a product question and is left as one. P2 — the hint told agents to read the bad value with `pad_item action=get`. They cannot: stripDuplicatedFieldsKeys removes implementation_notes and decision_log from every MCP response's fields blob, and the top-level arrays come from the extractor, which returns nil for exactly this shape. The value is invisible on the whole surface. The hint now says so and routes to a human, who can read it with `pad item show --format json`. P2 — `fields` holding a literal `null` unmarshals into a NIL map with no error, and both Append* helpers assign into what they get back, so `pad item note` PANICKED ("assignment to entry in nil map") instead of appending. Reproduced, fixed in parseMutableItemFields, and pinned by a test that fails on a panic rather than taking the process down. An absent blob and a null blob mean the same thing to every caller. Pre-existing, but it sits in the function family this bug is about and the message was about to recommend the command that panics. nit — README claimed a "closed eight-code taxonomy" (17 codes, and I had just added one) and read as if create lowers into fields_patch. Claude-Session: https://claude.ai/code/session_017jD6t1zjxGSq47SQpZfp1V * fix(models,mcp): predicate matches the append on malformed blobs; stop promising a broken workaround (Codex round 4) P1 — round 3 exempted `github_pr` from the update gate on the strength of noRemoteEquivalent's documented workaround. That workaround does not work: ingestFieldKVP (remote) and parseFieldFlag (CLI, and so stdio) both store a `field` value as a STRING, so the PR data lands double-encoded and no link appears — the BUG-2627 shape one key over. Filed as BUG-2696 with the three candidate fixes; NOT folded in, because the narrowest of them changes how every field value is typed. The exemption stands regardless: refusing would leave remote agents with strictly less than a broken door. What changes is what we may PROMISE. The catalog, instructions.md, version.go and README said "this is how you link a PR"; they now say the door is open and broken, and to hand PR linking to a human. Advertising a capability that isn't there is the failure mode this whole unit keeps circling. P2 — StructuredFieldIsAppendable returned TRUE when the whole fields blob was unparseable, on the reasoning that a broken outer blob is a different problem. True of the cause, irrelevant to the caller: the Append* helpers bail on that same parse, so the message again named a command that fails. It now returns false, which is simply the honest answer to the question asked, and the agreement table grew a malformed-outer-blob leg — the gap that let the disagreement through. P2 — the message claimed a raw field write always stores something Pad cannot read back. That holds for the CLI and MCP (a `--field` value is typed by schema lookup and these keys are in no schema) but not for a direct REST caller sending a valid array, who is refused for ownership reasons alone. Reworded to say both parts. nit — a misplaced parenthetical in the README read as if item CREATE lowers into fields_patch. It does not; it sends the full blob. Claude-Session: https://claude.ai/code/session_017jD6t1zjxGSq47SQpZfp1V * fix(mcp,models): stop the remote hint advertising the broken PR workaround; classify an unparseable blob as retry-hostile (Codex round 5) P1 — I corrected four artifacts that pointed agents at the github_pr field write and missed the fifth: noRemoteEquivalent's own text, which IS the message a remote agent receives when it calls `github link`, and which Codex had quoted at me in round 3 to establish the workaround existed. The nearest artifact to the actor was the one I did not open. Both entries now say there is no working remote path and name BUG-2696, with a test pinning the negative so a future edit cannot quietly reinstate the advice while the write is still broken. P2 — a fields blob that will not parse at all produced a bare parse error, so `note` / `decide` reached agents as `server_error`: transient- looking, and therefore retried, for a failure that is as deterministic as the per-key one BUG-2675 exists for. Both Append* helpers now wrap that parse failure in ErrStructuredFieldUnreadable, which both transports already classify, and the malformed-blob test asserts the sentinel rather than just an error. Claude-Session: https://claude.ai/code/session_017jD6t1zjxGSq47SQpZfp1V * docs(mcp,cli): qualify what an agent can actually see when the state is unreadable (Codex round 6 nit) Round 5 widened stored_state_unreadable to cover a fields blob that fails to parse outright, which made half of its own hint false: MCP's normalization strips a broken structured KEY (so `get` hides it), but leaves an unparseable BLOB as a raw string (so `get` shows it). The hint and instructions.md asserted the first case for both. Now stated per layer, in the two paired constants and the instructions. The reason it is worth the words rather than being cut: an agent told 'you cannot see this' does not look, and would have missed a value that was in fact right there in the response it already had. Claude-Session: https://claude.ai/code/session_017jD6t1zjxGSq47SQpZfp1V * fix(mcp): classify the move/copy reserved-key refusal as validation on stdio too (Codex round 7) P2 — carried over from v0.22, surfaced because THIS bump documents the two reserved-key refusals as agreeing across transports. The move/copy message ("Field(s) reserved for system metadata and not settable here") matched none of the stdio validation patterns, so the same deterministic 400 arrived as validation_failed on remote and server_error on stdio — and server_error reads as transient, so an agent retries a refusal that can never pass. One pattern added, plus a test that drives both real classifiers with the real server message text for both refusals, so a reworded message that stops matching fails here rather than in the field. nit — the github_pr exemption is UPDATE-only; move and copy still refuse it, because there the argument is BUG-2674's (an override reintroduces the key the migration just dropped), not this one's. The catalog and instructions said "not refused" without that qualifier. Claude-Session: https://claude.ai/code/session_017jD6t1zjxGSq47SQpZfp1V * fix(mcp): cover the copy path's own refusal wording in the stdio classifier (Codex round 8) P2 — round 7 fixed the MOVE wording; the copy path words the same class of refusal differently ("Destination collection has no field(s): ..."), so it kept arriving as server_error on stdio and validation_failed on remote. Third message in one family, and the round-7 test used the move text for every case, which is why it missed this. The parity table now carries all three real messages plus a control leg using one the pattern list already covered — without it the table could pass by matching everything. Recorded in the pattern list's comment rather than left implicit: matching prose is a stopgap, the structural fix is the pad-structured-error/v1 marker that carries the code instead of inferring it, and until a refusal emits one, this test is where a new wording has to be added. Claude-Session: https://claude.ai/code/session_017jD6t1zjxGSq47SQpZfp1V * test(mcp): use the real upstream codes in the parity fixtures (Codex round 9 nit) The copy legs carried `validation_error` where the handlers actually emit `malformed_override` and `invalid_override`. The 400 branch ignores the body code today, so the test passed either way — which is exactly why the fixture mattered: it was quietly recording a wrong contract, and a future code-aware classifier would regress against a table that agrees with it. Claude-Session: https://claude.ai/code/session_017jD6t1zjxGSq47SQpZfp1V * docs(mcp): the upstream code is not forwarded to MCP clients (Codex round 10 nit) The catalog said the server's own code (validation_error / malformed_override) appears in the MCP message. It does not: the 400 branch emits code=validation_failed with a fixed "Validation failed." message and the server's text in the HINT, discarding the finer-grained code. Reworded to say what an agent actually receives, and to say that telling the two refusals apart means reading the message. Also carried the update-only qualifier on the github_pr exemption into the README, matching the catalog and instructions. Claude-Session: https://claude.ai/code/session_017jD6t1zjxGSq47SQpZfp1V * docs(items): state the exemption predicate, not the exemption list (lead ruling) The lead's ruling on the github_pr reversal: make the REASON what the code says, so the next key added to reserved metadata is evaluated against 'does this audience have a real writer?' rather than pattern-matched onto a list that happened to be wrong for one key. Claude-Session: https://claude.ai/code/session_017jD6t1zjxGSq47SQpZfp1V	2026-08-19 23:17:24 -04:00
xarmian	bed933d7fd	feat(items): field-level PATCH + conflict envelope + read-only version history (TASK-2022) (#876) ... * feat(items): field-level PATCH + conflict envelope + version history Adds three related item-update primitives (TASK-2022 / IDEA-1480): - Field-level merge: PATCH `fields_patch` shallow-merges onto the item's current fields INSIDE the write transaction (null deletes a key), so concurrent single-field updates no longer clobber each other via the full-blob read-modify-write. `pad item update` and the MCP `pad_item.update` action now send only the changed keys. - Optimistic concurrency: optional `expected_updated_at` on update; on mismatch the store returns *UpdateConflictError and the handler emits the pad-structured-error/v1 conflict envelope (HTTP 409, code=update_conflict). Surfaced on CLI (`--expected-updated-at`) and MCP (`expected_updated_at`). - Read-only version history: `pad item history <ref>` (alias `versions`) and MCP `pad_item.history`, reusing the existing item_versions store + versions endpoint (no new store, no schema change). MCP ToolSurfaceVersion bumped 0.9 -> 1.0 (new action + param; update behavior change). No migration required. Claude-Session: https://claude.ai/code/session_019knGmnHcx5rrgWXQ8V8DZS * fix(items): address Codex review — dispatcher fields_patch, OCC ordering, date/required guards Round 1+2 review fixes for TASK-2022: - HTTP MCP dispatcher (dispatch_http_advanced.go) now sends fields_patch (only changed keys) instead of a client-side merged full fields blob, and forwards expected_updated_at — remote MCP callers get the same race-free merge + optimistic concurrency the CLI/HTTP paths do. - ValidatePartialFields rejects null-deleting a schema-declared REQUIRED field (would otherwise persist a blob the full-update validator rejects). - Open-children guard on the fields_patch path merges the patch onto the IN-TX locked row inside the precheck (not a stale pre-lock preview), so a priority-only patch can't false-fire the guard. - Optimistic-concurrency check now runs BEFORE the open-children precheck in the store, so a stale expected_updated_at yields update_conflict (not open_children) — single in-tx re-read shared by both. - Date auto-population on the patch path only fills an EMPTY current date; an existing end_date the caller isn't touching is preserved. Tests added for each fix. Claude-Session: https://claude.ai/code/session_019knGmnHcx5rrgWXQ8V8DZS	2026-07-08 16:47:34 -04:00
xarmian	342679a364	Standardize plan-limit error envelope across HTTP/MCP/CLI/UI (TASK-788) (#628) ... * fix: limit-hit responses were actively broken — garbled toasts, no upgrade signal The limit enforcement responses (plan_limit_exceeded on 403) used a flat body shape {"error": "plan_limit_exceeded", ...} that is incompatible with every consumer: the frontend PadApiError parser, the CLI parseError path, and the MCP classifyHTTPStatusKind all expect {"error": {"code": ..., "message": ...}}. As a result, hitting any of the 5 plan limits (items, members, workspaces, api_tokens, webhooks) produced garbled toasts with undefined message text and zero upgrade signal. Fix: - writePlanLimitError now emits the standard nested error envelope with a human-readable message sentence and limit details in error.details. - CLI parseError now correctly surfacing the message (net positive, no code change needed). - MCP classifyHTTPStatusKind: adds ErrPlanLimitExceeded to the taxonomy and the allowedStructuredErrorCodes whitelist so 403 plan-limit errors pass through with code + details rather than collapsing to ErrPermissionDenied (TASK-788). - Frontend: exports isPlanLimitError() type-guard and planLimitMessage() formatter from client.ts; all 4 limit-hit write call sites (item create, member invite, workspace create, token create) now branch on the code and show an upgrade-signal message pointing at /console/billing. - Test: updates handlers_workspace_cap_test.go to the new body shape; adds TestPlanLimitError_ResponseShape covering members_per_workspace limit hit. TASK-788 * fix(R1): cover MCP stdio path, 5 more item-create sites, polish message wording Finding A — MCP stdio transport was missing plan-limit coverage: - cli/client.go: add PlanLimitDetails struct, AsPlanLimit() helper, and WritePlanLimitError() that emits the pad-structured-error/v1 marker so the MCP stdio classifier can lift code + details instead of falling through to ErrServerError. - cmd/pad/main.go: wire the WritePlanLimitError branch into all three CreateItem call sites (item create, convention activate, playbook activate). - internal/mcp: add TestClassifyHTTPStatus_PlanLimitPreservesCodeAndDetails, TestClassifyHTTPStatus_Generic403FallsToPermissionDenied, TestClassifyExecError_PlanLimitMarkerLiftsStructuredPayload, and TestClassifyExecError_PlanLimitWithoutMarkerFallsThrough. Note: extractUpstreamErrorEnvelope already parses details (json.RawMessage field) — the codex concern about it being silently empty was a false alarm; no fix needed there. Finding B — 5 more item-create entry points were unguarded: - EditorBubbleMenu.svelte (inline wiki-link capture) - Sidebar.svelte (quick-add) - roles/+page.svelte (board new-item, was console.error only; adds toastStore) - conventions/+page.svelte - playbooks/+page.svelte (both create and duplicate paths) B1/B2 polish — server message is now statement-of-fact only, no doubled upgrade verb. planLimitMessage() drops "Upgrade to Pro to add more." (each surface appends its own CTA). limitStr uses hyphenated adjective form "3-member" / "10-item" (compound modifier before "limit"). TASK-788 * feat(task-788): extend MCP-stdio plan-limit coverage to workspace, invite, webhook Wire WritePlanLimitError into three additional CLI command error paths so the MCP stdio classifier surfaces ErrPlanLimitExceeded with details instead of falling through to ErrServerError: - workspaceCreateCmd: check before fmt.Errorf wraps the APIError - inviteCmd: check before returning the raw error - webhooksCreateCmd: check before returning the raw error Add TestClassifyExecError_PlanLimitWorkspaceCreate to exercise the full workspace-create stdio round-trip through classifyExecError, asserting ErrPlanLimitExceeded code, feature="workspaces", limit, and upgrade_url. Token create intentionally left bare (agents don't drive token creation).	2026-05-25 11:46:41 -04:00
xarmian	e59d3904c9	feat(server): refuse to mark item terminal while it has open children (IDEA-1494) (#571) ... * feat(server): refuse to mark item terminal while it has open children (IDEA-1494) Server-side guard inside handleUpdateItem that rejects a non-terminal → terminal done-field transition when the item still has at least one non-terminal child. Returns HTTP 409 with code=open_children plus a structured details payload listing each blocking child's {ref, title, status, collection_slug} so MCP-driven agents can self-recover (ship the listed children, then retry) and the CLI can render the same list verbatim. Escape hatch: `--force` on `pad item update` / `pad item bulk-update` and `force: true` on the MCP pad_item.action: update / bulk-update inputs both forward into the same ItemUpdate.Force transport field the handler consumes before any store mutation. Trigger conditions are tight: the PATCH must change the done-field key (resolved via TerminalValuesForDoneField against the parent's schema + settings) AND the new value must be terminal AND the current value must NOT already be terminal. Terminal → terminal and no-op terminal transitions bypass the guard; only entering the terminal set is gated. Per-child evaluation uses the child's own collection schema so hierarchical workspaces with custom typed collections work without extra plumbing. Tests cover: rejection with one open child (with mutation-safety assertion on the parent), no children, all-terminal children, --force override, no-op terminal → terminal, terminal → terminal, non-terminal → non-terminal, custom collection terminal_options honored, and a parent task (not a plan) — IDEA-1494 optional extra #3. MCP coverage asserts --force round-trips through both ExecDispatcher and HTTPHandlerDispatcher and is omitted when force=false. * fix(server): open-children guard round 2 — visibility, MCP pass-through, TOCTOU (IDEA-1494) Three Codex round-1 issues, each fixed with the recommended shape: P1 — visibility leak. The 409 response previously listed every blocking child by ref/title/status, including children in collections the caller couldn't see. The INVARIANT still evaluates against ALL children (it's a data-integrity gate — a restricted user must not be able to close a parent whose blockers they can't see), but the response payload now filters to caller-visible children only. Hidden blockers surface as a new `details.hidden_blocker_count` field plus an alternate human message when every blocker is hidden ("blocked by N open children you don't have access to"). Mirrors the visibility helpers (`visibleCollectionIDs` + `isItemVisibleToGuest`) used by the per-parent progress endpoint so the two paths can't drift. P2 — MCP code/details pass-through. The HTTP classifier was collapsing 409 into the generic `conflict` code and dropping `details`; the stdio classifier was matching the human "cannot " message against the validation regex and surfacing `validation_failed`. Both now surface `open_children` with the structured details intact: - HTTP: classifyHTTPStatusKind's 409 branch extracts the upstream code; any non-empty, non-"conflict" code is passed through with its `details` RawMessage. Generalizes beyond open_children — any future structured 409 from a handler gets the same treatment. - Stdio: the CLI writes a `pad-error: {json}\n` marker line on stderr before the human-readable block (single source of truth for both views), and classifyExecError detects the marker and lifts the envelope verbatim. Marker is duplicated as a const between internal/cli and internal/mcp to avoid pulling the cli package into the classifier just for one string. A new ErrOpenChildren error code constant + `Details json.RawMessage` field on ErrorPayload back the wire shape. P2 — TOCTOU. The guard previously ran in the handler before the store transaction began; a concurrent child insert / child status flip could slip between the children-list read and the parent's UPDATE. Fix: - New `Store.UpdateItemWithPreCheck(id, input, precheck)` runs the caller's invariant check inside the same tx, after acquiring the workspace seq lock AND a new parent-children advisory lock keyed on the parent ID. UpdateItem is now a thin wrapper passing nil. - Every UpdateItem unconditionally acquires the parent-children advisory lock for its own parent (if any) AND for itself-as-parent, in a fixed order (parent first) so two updaters touching the same parent always grab that key before the more-specific one — no AB/BA deadlock. - New `GetChildItemsTx` reads via the caller's tx; on Postgres the advisory lock provides the snapshot guarantee (DISTINCT precludes `FOR UPDATE`), on SQLite the global BEGIN IMMEDIATE write lock serializes all writers. - Handler now passes a precheck closure into UpdateItemWithPreCheck at all three call sites (collab-snapshot path, applier-direct-write path, main path). The guard's openChildrenGuardError sentinel is unwrapped after each call so the 409 surfaces cleanly. Tests: - TestOpenChildrenGuard_VisibilitySanitizesPayload — restricted editor sees parent + visible child, hidden child contributes to hidden_blocker_count, no leak of ref/title/slug. - TestOpenChildrenGuard_AllBlockersHiddenSurfaceGenericMessage — open_children=[], hidden_blocker_count>0, message mentions "you don't have access to." - TestOpenChildrenGuard_TOCTOURace — 8 iterations of a child-flip racing a parent-terminal update; asserts the forbidden outcome (parent=completed AND child=open) never occurs. - TestClassifyHTTPStatus_OpenChildrenPreservesCodeAndDetails + inverse generic-409 test. - TestClassifyExecError_OpenChildrenMarkerLiftsStructuredPayload + no-marker-falls-through inverse. * fix(server): open-children guard round 3 — 7 Codex findings closed (IDEA-1494) P1 — visibility fail-closed. The handler was swallowing visibleCollectionIDs errors, leaving visIDs==nil which the guard treats as unrestricted, leaking hidden-child metadata. Now surfaces the error as 500 BEFORE installing the precheck. Test: TestOpenChildrenGuard_VisibilityLookupErrorFailsClosed closes the store DB and asserts no 409+children leak. P1 — link mutations acquire the advisory lock. SetParentLink, ClearParentLink, CreateItemLink (when link_type ∈ childLinkTypes via new isChildLinkType helper), DeleteItemLink (same condition), and RestoreItem now take `pad:parent-children:<id>` in canonical sorted order via new AcquireParentChildrenLocks helper. SetParentLink locks BOTH old and new parents (re-parenting case). Race test TestOpenChildrenGuard_LinkMutationRace asserts the forbidden "link-committed-before-parent-flip AND parent flip succeeded" never occurs by comparing link.created_at to parent.updated_at. Documented semantics: status-wins + link-after-commit is legal under the invariant "no open children EXIST AT THE MOMENT of transition" — the post-condition variant ("no open child may EVER attach to a terminal parent") is intentionally deferred. P1 — MoveItem bypass closed. New MoveItemWithPreCheck mirrors UpdateItemWithPreCheck — acquires workspace seq lock + parent-children locks, re-reads in tx, runs caller precheck. handleMoveItem builds the same guard closure using the DESTINATION schema for done-field resolution (conservative — honors the schema the item moves INTO). CLI gains `pad item move --force`, client gains MoveItemWithForce that appends `?force=true` to the move endpoint. MCP catalog + mapItemMove forward `force` through the route mapper. Tests: TestOpenChildrenGuard_MoveItem_RejectsTerminalWithOpenChildren and …_ForceOverrides. P2 — pre-tx field-read TOCTOU. UpdateItemWithPreCheck and MoveItemWithPreCheck now re-read the item via new getItemTx INSIDE the tx (after locks) and pass that fresh snapshot to the precheck closure; the precheck classifies the transition against the in-tx view, not the handler-side pre-tx capture. Handler precheck closure swaps `currentFieldsJS` from the in-tx snapshot. Test: TestOpenChildrenGuard_PrecheckReadsInTxSnapshot stages a between-load status mutation and asserts the precheck observes the post-mutation fields. P2 — bulk-update carries structured errors. cmd/pad/main.go's updateFailure struct extended with Code + Details (json.RawMessage). When client.UpdateItem returns *cli.APIError, the row preserves the structured envelope. Human-text output also renders the open-children list inline. Chose JSON-envelope route over per-row stderr markers because bulk-update already produces a structured envelope and ExecDispatcher returns stdout verbatim on exit-0 — no classifier change needed. Test: TestBulkUpdateStructuredFailuresCarryOpenChildrenDetails confirms the wire shape the CLI lifts. P3 — marker hardening. Marker bumped to versioned form `pad-structured-error/v1:` (was `pad-error:`). cli.StructuredErrorMarker + mcp.structuredErrorMarker kept in lockstep with cross-references. mcp.allowedStructuredErrorCodes whitelists known codes (currently just open_children); unknown codes fall back to regex classification. Marker must start the line after whitespace trim (embedded markers ignored). Last-marker-wins to defeat pre-emption attacks. Tests: TestClassifyExecError_{UnknownStructuredCode,OldMarkerVersion, MarkerEmbeddedMidLine,LastMarker}. P3 — soft-deleted collection schemas honored. New GetCollectionAnyState mirrors childrenDoneFiltersForParent's inclusion rule; guard uses it so a child still attached to a soft-deleted collection is evaluated against ITS schema (custom terminal_options) instead of the default- status fallback (which would mis-classify and false-block). Test: TestOpenChildrenGuard_SoftDeletedCollectionSchemaHonored seeds a custom collection, soft-deletes it while a child remains, and asserts the terminal status is correctly recognized. Comprehensive store-mutation audit results recorded in the PR description (every method touching items.fields / items.collection_id or item_links). * fix(server): open-children guard round 4 — multi-parent locks, enum parity, PATCH atomicity (IDEA-1494) Four Codex round-3 (blast-radius lens) findings, each fixed with the recommended shape. P1 — multi-parent lock set. acquireParentChildrenLocksForUpdate and RestoreItem previously used `LIMIT 1` against item_links, so a child with BOTH a `parent` link to P1 AND an `implements` link to P2 only locked one of them. The other parent's open-children precheck could race against the child's status flip and miss it. Fix: new listParentChildLockKeys helper runs the same query GetChildItems' inclusion rule uses (childLinkTypes), returns ALL distinct parent target_ids, and feeds them into the canonical multi-lock helper. Both UpdateItemWithPreCheck and RestoreItem now acquire locks on {self} ∪ {all-parents-via-childLinkTypes}. Test: TestOpenChildrenGuard_MultiParentChildLocksAll races a child status flip against terminal-updates on both parents simultaneously. P2 — lock-order asymmetry. The pre-fix codebase had multiple lock- acquisition shapes: parent-then-self in acquireParentChildrenLocksForUpdate, single-key in RestoreItem / CreateItemLink / DeleteItemLink / ClearParentLink, and a sorted multi-key in SetParentLink. Two concurrent callers using different ad-hoc orderings could AB/BA deadlock. Fix: removed the per-call-site AcquireParentChildrenLock helper entirely. Every site now goes through AcquireParentChildrenLocks (the canonical sorted multi-lock helper) — including ones that need only one ID (the variadic call still sorts a one-element slice). The helper's doc comment explicitly states the contract: "Ad-hoc single-key acquisition outside this helper is FORBIDDEN — two call sites taking distinct keys in different orders WILL deadlock." Test: TestOpenChildrenGuard_NoDeadlockUnderReverseOrderConcurrency runs reverse-order re-parents with a 5-second timeout; assertion fails on hang. P2 — HTTP/stdio code-surface parity. Round 2's HTTP pass-through ("any non-conflict upstream code") silently widened the ErrorCode enum beyond stdio's allow-list (`open_children` only). Agents saw different code surfaces depending on which dispatcher delivered the response. Fix: HTTP 409 branch in classifyHTTPStatusKind now consults the same allowedStructuredErrorCodes whitelist stdio does. Codes outside the set collapse to ErrConflict (no details), matching what stdio does for an unknown-code structured marker. Doc on allowedStructuredErrorCodes updated to make the dual-consumer contract explicit: "Adding a new structured code is a TWO-WAY change." Tests: TestClassifyHTTPStatus_UnknownConflictCodeFallsBackToErrConflict and TestStructuredErrorCodeParityAcrossTransports. P3 — PATCH atomicity. A combined PATCH with `parent` + `status=terminal` on an item with open children used to commit the parent-link change INLINE (before the guard ran) and then reject the field write. Caller saw 409 but the parent had already moved. Fix: parent-link mutation is now DEFERRED — captured into outer- scope vars during fields validation, executed AFTER UpdateItemWithPreCheck succeeds. A guard rejection returns before the link write block, so on rejection the link is untouched. Documented choice: "reorder, don't tx-wrap" — wrapping SetParentLink into the same store tx would require threading a *sql.Tx through the SetParentLink API (which is also called from the handler_item_links path); reordering is the smaller surgery and gives the correct outcome on the failure direction. A residual window remains in the OTHER direction (field write commits, link write fails) — not made worse by the reorder, and called out inline for a future tx-wrap pass. Test: TestOpenChildrenGuard_PatchAtomicRejectionPreservesParentLink sets up target → oldParent → openChild, sends PATCH {parent=newParent, status=completed}, asserts 409 AND target.parent_link still points at oldParent. * fix(server): open-children guard — emit details.open_children as [] not null on hidden-only rejection (IDEA-1494)	2026-05-17 00:15:52 -04:00
xarmian	088ba2f839	fix(mcp): raise MCP per-token burst + classify 429 as ErrRateLimited (BUG-1430) (#546) ... * fix(mcp): raise MCP per-token burst + classify 429 as ErrRateLimited (BUG-1430) BUG-1409 reported an agent hitting "Pad backend 500s on parallel writes" during workspace onboarding via remote MCP on Pad Cloud. Triage split that umbrella into three children; this PR addresses BUG-1430 (the parallel-writes symptom). Root cause investigation showed the underlying write path is fine — local SQLite handled 24 parallel item-create POSTs cleanly (busy_timeout + BEGIN IMMEDIATE + WAL serialize writers without errors). The most plausible cause of the agent's "500 on parallel writes" report is the MCP per-token rate limiter (burst 20, 60/min) rejecting requests 21-24 of an onboarding burst with HTTP 429, which the dispatcher's classifier then collapsed into a generic ErrServerError envelope. Changes: - middleware_ratelimit.go: MCPPerToken burst 20 → 60. Sustained rate unchanged at 60/min/token. Matches the general API limiter's burst-60 per-user cap so the MCP path no longer imposes a tighter ceiling than the equivalent /api/v1 path. Comment expanded to record the rationale. - internal/mcp/errors.go: add ErrRateLimited error code and an explicit case http.StatusTooManyRequests in classifyHTTPStatusKind. 429s now surface as a first-class rate-limited envelope with an actionable hint pointing at Retry-After and the per-token cap, instead of landing in the generic ErrServerError "other 4xx" bucket. Agents implementing exponential backoff can switch on code without parsing free-form text. - handlers_cloud.go: add slog.Error instrumentation to enforcePlanLimit and enforceUserPlanLimit error paths. These are cloud-mode-only 500 candidates we couldn't exercise locally (local dev runs cloudMode=false); the structured logs give operators a grep-able tag the next time the symptom surfaces on real Pad Cloud, so we can rule the path in or out empirically without another investigation pass. - tests: bump iteration counts past the new burst (20 → 60), add 429 case to classifyHTTPStatus code-mapping table + envelope hint-shape table. Investigation context (full triage in BUG-1430): - ../pad-cloud sidecar is NOT in the /api/v1 or /mcp request path (nginx-router proxies those directly to pad backend). - featureCount + advisory-lock contention on Postgres remain plausible 500 candidates under heavy bursts; the new logging is intended to catch those if they fire. Siblings BUG-1431 (status field placement) and BUG-1432 (tags field) are tracked separately and not addressed here. * fix(mcp): drop hardcoded cap from rate-limit hint per Codex review (round 1) Codex round 1 [P2] caught that rateLimitHintFor's "the per-token cap is 60 req/min with a burst of 60" text was misleading: classifyHTTPStatusKind handles 429s from the dispatcher's SYNTHESIZED /api/v1/... requests, which come from the general API limiter (600/min, burst 60), the Search limiter (30/min, burst 10), and potentially others — NOT the MCP per-token limiter (which fires before the dispatcher runs and so never lands in this classifier path). Generalize the hint: point at Retry-After (which carries the correct limiter-specific wait) and drop the cap from prose. Update the matching test assertion to assert the generic shape ("burst-heavy" instead of "60 req/min").	2026-05-14 15:45:51 -04:00
xarmian	42f6ce96e1	fix(mcp): normalize error envelope shape + extend code taxonomy + actionable hints (TASK-1077/1078/1079) (#388) ... Three independent improvements bundled as one PR because they all touch the same dispatcher error-emission surface; landing them piecemeal would churn the same lines repeatedly. ## TASK-1077 — uniform envelope shape Pre-fix some dispatchers emitted plain-string errors via `mcp.NewToolResultErrorf("%s: %s failed: %s", ...)`. Same underlying 404 surfaced in three different shapes across the surface (item lookup → structured envelope; note/decide → "item note: prefetch: 404 ..."; bulk-update per-row → bare error string). Inconsistent shape made it hard for agents to reason about errors uniformly. Three new helpers in errors.go: - validationFailedResult(cmdKey, msg, fixHint) — replaces the "X is required" / "invalid Y" chain across every dispatcher. - dispatcherErrorResult(cmdKey, op, err) — replaces the internal "build request: %s" / "encode body: %s" / "parse current: %s" chain. Always emits ErrServerError with a programmer-readable Hint. - upstreamHTTPErrorResult(...) — wraps every in-handler prefetch / sub-call HTTP failure through classifyHTTPStatusKind so the shape matches the main pipeline's responses exactly. Every NewToolResultErrorf call site in internal/mcp/dispatch_http*.go + catalog.go retrofitted. bulk-update's per-row `Error string` field flipped to `Error *ErrorPayload` so every row failure carries the same {code, message, hint} shape as a top-level failure. ## TASK-1078 — resource-kind-aware error codes Pre-fix every 4xx 404 collapsed to ErrItemNotFound regardless of what was being read; pad_workspace list returning 404 (route missing) reported `code: "item_not_found"` despite the call having nothing to do with items. Pre-fix every 5xx collapsed to ErrServerError, indistinguishable from dispatcher internal failures. Three new codes in errors.go: - ErrNotFound — resource-shaped 404s that AREN'T item lookups (collection, listing endpoint, link target, attachment). - ErrUpstreamError — 5xx with a structured body (transient backend failure). Distinct from ErrServerError (catch-all for dispatcher internal + un-mapped 4xx). - ErrBackendUnreachable — reserved for transport-level failures (DNS / connection refused / 5xx with no body); not yet emitted by classifyHTTPStatus but available for future transport-aware classification. - ErrWorkspaceRequired — reserved for the multi-workspace-token "ambiguous default" case (TASK-1076's deferred sister error; constant available even though dispatcher doesn't emit it yet). New ResourceKind enum (item/workspace/collection/listing/link/ attachment/unknown) lets callers tell the classifier what they were reading. classifyHTTPStatusKind is the new entry point; classifyHTTPStatus preserved as a legacy adapter for callers that haven't been retrofitted (pass ResourceUnknown → falls back to pre-TASK-1078 behaviour). Every retrofit call site passes its known kind + ref/slug, so 404s now route through the right code with a contextual message ("Item TASK-7 not found.", "Workspace foo not visible.", "Collection tasks not found.", etc.). ## TASK-1079 — actionable hints Pre-fix `hint` was usually `"404 page not found"` (chi's default NotFound body verbatim) or the upstream JSON envelope re-stringified. Either way: zero diagnostic value, sometimes outright misleading (double-stringified JSON in a hint field is hostile). Per-code hint generators in errors.go: - itemMissingHint — names the ref + route + suggests pad_item search / list as recovery. - workspaceMissingHint — names the slug + route + composes with the existing available_workspaces enrichment. - notFoundHintFor — kind-aware: collection 404 → "use pad_collection list to enumerate"; listing 404 → "verify the route matches the server's API surface (build version may be stale)"; etc. - authHintFor / permissionHintFor — point at re-auth / scope check. - upstreamHintFor — flags 5xx as "usually transient — retry once or check pad logs." extractUpstreamMessage parses pad's own structured `{error:{message}}` envelope when the upstream backend returned one, so hints lift the inner human-readable message out instead of dumping the literal JSON. Falls back to the raw body when the JSON shape doesn't match (no parse failure noise). ## Tests - TestDispatcher_AllErrorsUseStructuredEnvelope walks every special-case + link dispatcher's missing-required-input error path; pins the shape (code, message, hint all set; hint never just "404 page not found"). Adding a new dispatcher that uses NewToolResultErrorf will fail this test — it's the regression gate the DOD wants. - TestClassifyHTTPStatus_KindAware pins each ResourceKind → expected ErrorCode mapping for 404s. - TestClassifyHTTPStatus_HintsAreActionable pins that hints reference the actual route + ref + recovery tools, AND forbids the bare "404 page not found" passthrough that triggered Bug 17. - TestExtractUpstreamMessage covers the 7 input shapes the helper can see (structured envelope, empty inner, missing inner field, unparseable, wrong shape, empty, with extra fields). - Two existing tests updated to reflect the new shapes: TestClassifyHTTPStatus 5xx cases now expect ErrUpstreamError; TestMakeFanOutHandler_UnknownAction + TestActionEnv_Dispatch_ UnknownCmdPath substring searches updated for JSON-encoded quotes. ## Behavior diff agents will observe Same underlying 404, three example error envelopes: pad_item show TASK-MISSING: code: "item_not_found" message: "Item not found." hint: "Item \"TASK-MISSING\" not found. Route: /api/v1/.../items/TASK-MISSING. Try `pad_item search` or `pad_item list` to find the right ref." pad_workspace list (route 404): code: "unknown_workspace" message: "Workspace not visible to this session." hint: "Route: /api/v1/workspaces. Available workspaces: docapp, pad-web." pad_project dashboard (workspace doesn't exist): code: "unknown_workspace" message: "Workspace \"missing\" is not visible to this session." hint: "Workspace \"missing\" not visible. Route: /api/v1/workspaces/missing/dashboard. Available workspaces: docapp." Backend 500: code: "upstream_error" message: "pad item show failed: backend returned 500" hint: "Backend returned 500. Usually transient — retry once or check pad logs for the underlying error. Route: ..."	2026-05-02 22:10:12 -04:00
xarmian	55d3a078a8	fix(mcp): standup CLI ref + classifier polish for BUG-987 round 2 (#362) ... Round-2 hotfix on top of PR #361 (which shipped to v0.1.0-rc.4). Claude Desktop's re-review of rc.4 surfaced two fixes that didn't fully land: - Bug 8 (round 1 went to wrong layer). My HTTPHandlerDispatcher fix populated ref on standup blockers, but Claude Desktop's path is ExecDispatcher → CLI subprocess → standupCmd, which has its own JSON composition struct. That struct's Attention + SuggestedNext anonymous types didn't even define ItemRef as a parseable field. Now both define `item_ref` and the JSON-emit loops set Ref from it. Verified live: blockers now carry refs (TASK-X), not empty strings. - Bug 11 part 2. Round 1 stripped the cobra Usage block but two artifacts still leaked: 1. The "pad <verb> failed: <stderr>" prefix on server_error fallback messages. The verb name is the OLD CLI verb (e.g. `pad item block`) which doesn't match the v0.2 catalog actions agents see, and the cmdPath is already implicit from the invoked tool. Drop the prefix; emit the cleaned stderr directly. 2. Self-link / "cannot ..." validation rejections classified as server_error instead of validation_failed. Extended the validation regex with `cannot ` so server-side rejections like "cannot link an item to itself" / "cannot modify archived item" route to ErrValidationFailed. Verified live with a self-link attempt — now returns code=validation_failed, hint="cannot link an item to itself", no prefix. - New stripErrorPrefix helper trims leading `Error:` / `error:` / `ERROR:` from every classified hint+message so the envelope text isn't redundant with the envelope's `code` signal. Bug 13 / Bug 14: my round-1 fixes verified working locally on rc.4 (tested with a fresh Task → convention=None; dashboard by_role shows "Unassigned"/"unassigned" for the bucket). The reviewer's stale results almost certainly reflect a pad server process that wasn't restarted with the rc.4 binary swap. Tests: - TestClassifyExecError_CannotPhrasingClassifiesAsValidation — three "cannot ..." stderr cases must classify validation_failed. - TestClassifyExecError_NoLegacyVerbPrefixInMessage — pins the prefix-strip behaviour on the server_error fallback path. - TestStripErrorPrefix — trim-rule round-trip across casing variations and empty input. Parent: BUG-987.	2026-05-01 21:04:26 -04:00
xarmian	0f05012169	fix(mcp): six surgical fixes for BUG-987 (bugs 6, 8, 11, 12, 13, 14) (#361) ... * fix(mcp): six surgical fixes for BUG-987 (bugs 6, 8, 11, 12, 13, 14) Hotfix follow-up to v0.1.0-rc.3's Claude Desktop dogfood. Six surgical fixes; bigger items (5, 7, 9, 10) deferred to separate tasks. - Bug 6: `pad project next --format json` was emitting the entire dashboard, indistinguishable from `pad project dashboard --format json`. Now slices to suggested_next only. cmd/pad/main.go. - Bug 8: standup blockers carried empty `ref` strings, blocking agent linkback to the actually-blocked items. dashboard's attention[].item_ref is canonical; the standup composer in internal/mcp/dispatch_http_slice4.go just wasn't propagating it. Same fix applied to suggested_next entries. - Bug 11: cobra's auto-emitted "Usage: pad item block ..." help block leaked into MCP error envelopes via classifyExecError. The Usage text references OLD CLI verb names (pre-v0.2 catalog) that agents using the new surface have no business seeing, and bloats every error response. New stripCobraUsageBlock helper truncates stderr at the first line-anchored "Usage:" marker before classification + envelope construction. - Bug 12: BuildCLIArgs validation errors (missing required arg, type mismatch) came out of env.Dispatch as bare-text NewToolResultErrorf results, breaking the structured envelope contract. New helper validationFailedFromBuildErr wraps them as ErrValidationFailed envelopes with the field name extracted via regex from the underlying message. - Bug 13: every Task / Idea / Plan with a `priority` field got a phantom `convention: { enforcement: "<priority>" }` surfaced on its response, because ExtractItemConventionMetadata's legacy fallback treated `priority` as the Convention enforcement tier unconditionally. Restructured to track hasConventionShape separately from hasMetadata — only Convention-specific markers (structured convention field, trigger, scope, surfaces, commands, direct enforcement) flip the shape flag. category alone is insufficient (Ideas / Bugs / Roadmap items legitimately use it). Final guard returns nil when only category was matched. - Bug 14: GetRoleBreakdown's unassigned row was emitted with empty role_name + role_slug, presenting as a "phantom" entry in the dashboard. Now explicitly labelled "Unassigned" / "unassigned" while keeping role_id null so it's still distinguishable from a real role. Tests: - internal/mcp/bug987_test.go (new) — stripCobraUsageBlock + classify + validation envelope wrapping + env.Dispatch integration. - internal/models/item_test.go — three cases covering non-Convention items (Task, Idea, Plan with priority) returning nil metadata, and one preservation test for legacy Conventions with priority field. - internal/store/agent_roles_test.go (new) — confirms unassigned row carries explicit "Unassigned" / "unassigned" labels. Live verified: pad_project action=next returns just the suggestions array; pad_item action=create with no fields returns validation_failed with field=collection; pad_item action=link with self-target returns without Usage-block leakage. Deferred to separate items (per BUG-987 triage): - Bug 5: text vs JSON returns across note, decide, star, unstar, delete, bulk-update — needs CLI-side handler updates per command. - Bug 7: suggested_next algorithm — needs to consider in-progress items, not just open ones; behavior change needs design. - Bug 9: fields/tags double-stringified — potentially breaking for web UI/CLI consumers. - Bug 10: decision_log/notes embedded in fields blob duplicating top-level arrays — might require data migration. Parent: BUG-987. * fix(mcp): HTTP transport equivalence + ordering for BUG-987 per Codex review (round 1) Two findings from Codex review of PR #361: 1. project.next on HTTP transport still returned the full dashboard. The route table mapped "project next" directly to /dashboard, so the CLI fix (slice to suggested_next) didn't reach OAuth-authed agents going through HTTPHandlerDispatcher. Catalog actions must produce equivalent shapes on stdio and HTTP — that's the contract that lets agents be transport-agnostic. Fix: new dispatchProjectNext method on HTTPHandlerDispatcher that fetches the dashboard via the existing fetchDashboardJSON helper, slices to suggested_next[], re-encodes, and runs through packageJSONResult so it gets the same {items: [...]} wrap as other list responses. Also retires the broken route-table entry — replaced with a comment pointing at the new method so future contributors don't re-add a passthrough. Test: TestDispatch_ProjectNext_SlicesToSuggestedNext + the empty- array case. Asserts dashboard-only top-level fields (summary, active_items) don't leak into the response — that's the whole point of project.next being distinct from project.dashboard. 2. ExtractItemConventionMetadata's priority→enforcement legacy fallback ran BEFORE surfaces/scope/commands had a chance to flip hasConventionShape, so a Convention with only `{scope, priority}` would silently drop enforcement. Fix: move the priority fallback to AFTER all marker checks. Direct `enforcement` still resolves first; the legacy priority fallback runs at the bottom once shape detection is complete. Tests: two new cases covering scope-only and commands-only legacy Conventions — both must resolve enforcement via the priority fallback. Parent: BUG-987.	2026-05-01 20:39:10 -04:00
xarmian	1e94fcbd9d	feat(mcp): structured MCP error envelopes with closed taxonomy (TASK-973) (#357) ... * feat(mcp): structured MCP error envelopes with closed taxonomy (TASK-973) Replaces raw stderr / status-text passthrough with a closed-set ErrorCode taxonomy + structured ErrorEnvelope. Agents can now branch on `error.code` instead of parsing free-form text: { "error": { "code": "no_workspace", "message": "No workspace context. Pass `workspace` explicitly, ...", "hint": "Available workspaces: docapp, pad-web", "available_workspaces": [{"slug": "docapp", "default": true}, ...] } } Taxonomy (8 codes): - no_workspace, unknown_workspace — populate available_workspaces - auth_required, permission_denied - item_not_found, validation_failed, conflict - server_error (catch-all) Implementation: - internal/mcp/errors.go (new): ErrorCode constants, ErrorEnvelope + ErrorPayload + WorkspaceHint types, NewErrorResult constructor, classifyExecError + classifyHTTPStatus dispatchers, regex pattern matchers for stderr classification, WorkspaceLister interface for hint enrichment. - internal/mcp/dispatch.go: ExecDispatcher.Dispatch routes failures through classifyExecError (with itself as the WorkspaceLister). Adds ListWorkspaces method that shells out to `pad workspace list --format json`. Adds RootArgs field so the listing inherits root flags (--url etc.). - internal/mcp/dispatch_http.go: packageHTTPResponse routes 4xx/5xx through classifyHTTPStatus. Lookup is intentionally nil here — TASK-977 (PLAN-943) owns the privacy-preserving available_workspaces filtering by OAuth allow-list. - cmd/pad/mcp.go: pre-flatten rootFlags into RootArgs at dispatcher construction. NewErrorResult emits BOTH structured content (for Claude Desktop, Cursor) AND a JSON text body (for older clients). Both decode to the same envelope so wire-level shape stays uniform. Tests: - TestNewErrorResult_Envelope: round-trip the envelope through structured + text surfaces. - TestClassifyExecError: 11 cases covering every taxonomy code via stderr patterns. - TestClassifyExecError_LookupFailureStillReturnsEnvelope: lookup failures degrade to empty available_workspaces, never drop the whole envelope. - TestClassifyHTTPStatus: 10 cases covering each HTTP status mapping including the workspace-vs-item 404 fork. - TestParseWorkspaceListJSON: happy path, empty / null / malformed, entry-without-slug skipping. - TestExtractUnknownWorkspaceSlug: regex helper round-trip. Out of scope (per task description): - HTTPHandlerDispatcher available_workspaces filtering by OAuth allow-list → TASK-977 (PLAN-943). - item_not_found "recent items" hint enrichment → also TASK-977. - Per-code docs page on getpad.dev/mcp/local → TASK-976. Parent: TASK-973 → PLAN-969. * fix(cli): add JSON output to pad workspace list per Codex review (round 1) Codex P2: classifyExecError's WorkspaceLister side channel calls `pad workspace list --format json` to populate available_workspaces in no_workspace / unknown_workspace error envelopes (TASK-973). The CLI command silently ignored formatFlag and always printed the human-readable shape, so parseWorkspaceListJSON would fail and the hint was effectively never populated. Add JSON branch to workspacesCmd that emits a {slug, name, updated_at, default} array. The `default: true` flag marks the CWD-linked workspace so agents can prefer it without a separate DetectWorkspace call. Manual verification: $ pad workspace list --format json | jq '.[0]' { "slug": "docapp", "name": "pad", "updated_at": "2026-04-14T13:24:51Z", "default": true } Parent: TASK-973 → PLAN-969. * fix(mcp): tighten unknown-workspace slug regex per Codex review (round 2) Codex finding: extractUnknownWorkspaceSlug's bare-word regex captured stop-words like "not" out of generic "Workspace not found" messages. The server emits exactly this generic body in middleware_auth.go and handlers_workspaces.go, so the resulting envelope would say `Workspace "not" is not visible to this session.` — pushing agents toward retrying with a bogus slug. Tighten the regex to only match QUOTED slug forms ("workspace 'foo'" or "workspace \"bar\""). Bare-word phrasings yield empty slug, and unknownWorkspaceResult now emits a generic "Workspace not visible to this session." instead of the misleading empty-string `Workspace ""`. Test cases updated: - "workspace 'foo' does not exist" → "foo" (still works) - "workspace \"bar\" not found" → "bar" (still works) - "unknown workspace baz" → "" (was "baz", now intentionally empty) - "workspace docapp not visible" → "" (was "docapp", now empty) - "Workspace not found" → "" (the actual server response) The other taxonomy / hint behavior is unchanged: ErrUnknownWorkspace still classifies correctly, available_workspaces still populates from ListWorkspaces, and the body text still appears in Hint via the classifyHTTPStatus 404 branch's body-append logic. Parent: TASK-973 → PLAN-969.	2026-05-01 18:32:27 -04:00