@withpica/mcp-server 2.98.0 → 2.100.0

package/dist/tools/credits.js

@@ -73,6 +73,55 @@ function recordingCreditExists(err) {
     return typedError("RECORDING_CREDIT_EXISTS", body.message ??
         `This person is already credited in this role on this recording${creditId ? ` (credit ${creditId})` : ""} with different details. Nothing was changed — one person holds one credit per role. Edit that credit with pica_credit_update (e.g. instrument: "drums, guitar") instead of adding a second.`, creditId ? { existing_credit_id: creditId } : undefined);
 }
+/**
+ * The columns that record a master credit's attestation. Mirrors
+ * RECORDING_CREDIT_ATTESTATION_FIELDS in
+ * lib/constants/recording-credit-attestation.ts, which
+ * POST /api/admin/recordings/[id]/credits and the bulk route refuse with the
+ * same code; this package cannot import the app.
+ */
+const RECORDING_ATTESTATION_FIELDS = [
+    "attestation_status",
+    "attested_at",
+    "attested_by",
+    "attestation_source_type",
+    "attestation_source_id",
+];
+/**
+ * Refuse a pica_recording_credits_update call that carries any attestation
+ * column — at the top level (single form) or on any credits[] entry (batch
+ * form). Presence is what counts: "pending" is refused too, so no caller is
+ * left believing it controls the field. Returns null when the call is clean.
+ */
+function refuseRecordingAttestation(args) {
+    const has = (o) => {
+        if (!o || typeof o !== "object")
+            return null;
+        for (const f of RECORDING_ATTESTATION_FIELDS) {
+            if (Object.hasOwn(o, f))
+                return f;
+        }
+        return null;
+    };
+    const guidance = "Every credit starts as pending and only the credited person can " +
+        "confirm it. Remove it and retry (put any source evidence in notes), " +
+        "then ask them to confirm with pica_collaborators_invite (recording_id) " +
+        "or pica_credits_send_for_attestation on the recording's song.";
+    const topField = has(args);
+    if (topField) {
+        return typedError("ATTESTATION_NOT_SETTABLE", `${topField} can't be set by this tool — nothing was saved. ${guidance}`, { field: topField });
+    }
+    if (Array.isArray(args.credits)) {
+        for (let i = 0; i < args.credits.length; i++) {
+            const field = has(args.credits[i]);
+            if (field) {
+                return typedError("ATTESTATION_NOT_SETTABLE", `credits[${i}] carries ${field}, which this tool can't set — ` +
+                    `nothing was saved. ${guidance}`, { field, index: i });
+            }
+        }
+    }
+    return null;
+}
 export class CreditsTools {
     pica;
     constructor(pica) {
@@ -154,8 +203,10 @@ export class CreditsTools {
                         "'publisher' (their publishing share is that entry's split) — " +
                         "there is no separate publisher field. is_primary marks the " +
                         "primary attribution and applies to composition credits only " +
-                        "(recording credits have no primary flag). You can also set notes " +
-                        "and attestation_status. Once it's saved, it's worth asking the " +
+                        "(recording credits have no primary flag). You can also set notes. " +
+                        "Attestation is not settable here: every credit this saves starts " +
+                        "as pending, and only the credited person confirms it — send it " +
+                        "with pica_credits_send_for_attestation. Once it's saved, it's worth asking the " +
                         "user: send these to the collaborators to verify, or generate a " +
                         "split sheet for sign-off? Is anyone here on a work-for-hire or " +
                         "producer agreement (a producer takes points off the top of " +
@@ -221,11 +272,6 @@ export class CreditsTools {
                                             type: "string",
                                             description: "Free-text notes about this credit (e.g., recording-session context, contribution specifics).",
                                         },
-                                        attestation_status: {
-                                            type: "string",
-                                            enum: ["pending", "attested", "disputed", "declined"],
-                                            description: "Attestation status. Default: pending. Service-managed fields attested_at / attested_by are set by the attestation workflow, not this tool.",
-                                        },
                                     },
                                     required: ["person_id", "role", "splits"],
                                 },
@@ -237,7 +283,7 @@ export class CreditsTools {
                     nextSteps: [
                         {
                             tool: "pica_credits_list",
-                            reason: "Read the credits back to confirm every advertised field (is_primary, notes, attestation_status) actually persisted. Silent persistence drops are real — never trust the write response alone.",
+                            reason: "Read the credits back to confirm every advertised field (is_primary, notes) actually persisted. Silent persistence drops are real — never trust the write response alone.",
                             when: "on_success",
                         },
                         {
@@ -286,6 +332,10 @@ export class CreditsTools {
                         "Arranger, Programmer, Other. Look up the person first with " +
                         "pica_people_query; if they're not in the catalog, leave " +
                         "person_id empty and their name still shows via credited_name. " +
+                        "Attestation is not settable here: every credit starts as " +
+                        "pending and only the credited person confirms it — ask them " +
+                        "with pica_collaborators_invite (recording_id) or " +
+                        "pica_credits_send_for_attestation on the recording's song. " +
                         "After saving, confirm it stuck with pica_recordings_inspect " +
                         "(sections: ['recording_credits']). → then: " +
                         "pica_recordings_inspect (verify saved), pica_people_query " +
@@ -329,11 +379,6 @@ export class CreditsTools {
                                 type: "string",
                                 description: "Optional free-text notes about this credit (recording-session context, role specifics).",
                             },
-                            attestation_status: {
-                                type: "string",
-                                enum: ["pending", "attested", "disputed", "declined"],
-                                description: "Optional starting attestation status — master credits are attestable just like composition credits. Defaults to 'pending'. Use pica_credits_send_for_attestation to ask the credited person to confirm; attested_at / attested_by are set by the attestation workflow, not this tool.",
-                            },
                             instrument: {
                                 type: "string",
                                 description: "Optional instrument(s) for this credit, e.g. 'drums' or 'drums, bass' (one credit per person — list multiple instruments on the same row). Stored on recording_credits.instrument and rendered in /inspect's contributors table.",
@@ -408,96 +453,6 @@ export class CreditsTools {
                 },
                 executor: withBillingGate(this.pica, "recording credit update", this.updateRecordingCredits.bind(this)),
             },
-            // ADR-264 WS4 prerequisite — bulk recording credits. One album's
-            // production credits stops being 30 sequential per-recording calls.
-            {
-                definition: {
-                    name: "pica_recording_credits_bulk_update",
-                    scope: "write:catalog",
-                    audiences: ["stdio", "http"],
-                    tier: "write",
-                    description: "Apply one set of recording credits across many recordings in a " +
-                        "single call. Use when the user asks: 'credit the producer on " +
-                        "the whole album', 'add these credits to every track', 'backfill " +
-                        "the engineer across these recordings'. Target either a release " +
-                        "(release_id — every recording on its tracklist) or an explicit " +
-                        "recording_ids list, never both. The same credit set is applied " +
-                        "to EVERY target recording; credits that already exist on a " +
-                        "recording (same credited name + role) are skipped, never " +
-                        "overwritten, so re-running is safe. Set dry_run: true first to " +
-                        "preview exactly which rows would be created vs skipped. Caps: " +
-                        "100 recordings, 50 credits, 500 total rows per call. Per-track " +
-                        "differences (a featured artist on track 3 only) go via " +
-                        "pica_recording_credits_update on that recording. → then: " +
-                        "pica_recordings_inspect (verify saved)",
-                    workflows: ["recording-credits-required"],
-                    vernacular_kind: "specialist",
-                    vernacular_reason: "Specialist context; not yet covered by the Creator Question Atlas — pending telemetry-driven addition per ADR-226 Phase 4 substrate writes.",
-                    previewMode: "dry_run",
-                    inputSchema: {
-                        type: "object",
-                        properties: {
-                            release_id: {
-                                type: "string",
-                                description: "UUID of a release — targets every recording on its tracklist. Provide exactly one of release_id / recording_ids.",
-                            },
-                            recording_ids: {
-                                type: "array",
-                                items: { type: "string" },
-                                description: "Explicit recording UUIDs to credit (max 100). Provide exactly one of release_id / recording_ids.",
-                            },
-                            credits: {
-                                type: "array",
-                                description: "The credit set applied to EVERY target recording (max 50). Each entry needs credited_name + role; person_id links an existing person record (resolve via pica_people_query first).",
-                                items: {
-                                    type: "object",
-                                    properties: {
-                                        credited_name: {
-                                            type: "string",
-                                            description: "The displayed credit name — the contributor's professional name as it should appear on the recording.",
-                                        },
-                                        role: {
-                                            type: "string",
-                                            enum: [...RECORDING_CREDIT_ROLES],
-                                            description: "Recording credit role from the 16-entry RECORDING_CREDIT_ROLES enum. Songwriting roles (Writer, Composer, Lyricist) belong on the work via pica_credits_update.",
-                                        },
-                                        person_id: {
-                                            type: "string",
-                                            description: "Optional UUID of an existing person record in the catalog. Leave empty if the contributor has no person record — credited_name still shows.",
-                                        },
-                                        split_percentage: {
-                                            type: "number",
-                                            description: "Optional percentage share for this credit (0-100), applied identically on every target recording.",
-                                        },
-                                        split_type: {
-                                            type: "string",
-                                            description: "Optional free-form split type label (e.g. 'master', 'producer_points').",
-                                        },
-                                        notes: {
-                                            type: "string",
-                                            description: "Optional free-text notes attached to each created credit row.",
-                                        },
-                                    },
-                                    required: ["credited_name", "role"],
-                                },
-                            },
-                            dry_run: {
-                                type: "boolean",
-                                description: "When true, returns the per-row would_create / would_skip_existing decision set without persisting anything. Preview before committing.",
-                            },
-                        },
-                        required: ["credits"],
-                    },
-                    nextSteps: [
-                        {
-                            tool: "pica_recordings_inspect",
-                            reason: "Read recording_credits back via sections:['recording_credits'] on a sample recording to confirm the rows persisted.",
-                            when: "on_success",
-                        },
-                    ],
-                },
-                executor: withBillingGate(this.pica, "bulk recording credit update", this.bulkUpdateRecordingCredits.bind(this)),
-            },
             // ADR-232 — atomic credit primitives. Composable verbs over the same
             // substrate as pica_credits_update / pica_recording_credits_update,
             // but discrete: add one row, remove one row, no replace-semantics.
@@ -631,8 +586,8 @@ export class CreditsTools {
                                 description: "(recordings only) Displayed credit name (NOT NULL on recording_credits). Required for recordings.",
                             },
                             share_pct: {
-                                type: "number",
-                                description: "Percentage share (0-100). Maps to split_percentage on work_collaborators (composition) / recording_credits (master). Omit when unknown — it is stored as NULL (unknown), never as 0; the health plan then reports the work as incomplete rather than rescaling the others. REQUIRED for credit_type 'owner' (master ownership is recorded as given, never assumed 100).",
+                                type: ["number", "null"],
+                                description: "Percentage share (0-100). Maps to split_percentage on work_collaborators (composition) / recording_credits (master). Omit it (or send null) when unknown — it is stored as NULL (unknown), never as 0; the health plan then reports the work as incomplete rather than rescaling the others. REQUIRED for credit_type 'owner' (master ownership is recorded as given, never assumed 100).",
                             },
                             notes: {
                                 type: "string",
@@ -668,14 +623,20 @@ export class CreditsTools {
                     audiences: ["stdio", "http"],
                     tier: "write",
                     description: "Edit ONE existing credit in place — change a writer's share, an " +
-                        "instrumentalist's instrument, a role, the displayed name or the " +
-                        "notes — leaving every other credit exactly as it is. Use when the " +
-                        "user asks: 'change Mary's split to 40', 'set Charlie's instrument " +
-                        "to bass', 'fix the spelling of this credit'. This is the verb " +
-                        "between pica_credit_add and pica_credit_remove: it never " +
-                        "replaces the set (that is pica_credits_update) and never " +
-                        "deletes-and-recreates, so the credit keeps its id and " +
-                        "attestation state. Find the credit_id with pica_credits_list. " +
+                        "instrumentalist's instrument, a role, the displayed name, the " +
+                        "notes, or WHO the credit is for (person_id) — leaving every " +
+                        "other credit exactly as it is. Use when the user asks: 'change " +
+                        "Mary's split to 40', 'set Charlie's instrument to bass', 'fix " +
+                        "the spelling of this credit', 'link the Brian Lucey credit to " +
+                        "his new person record'. This is the verb between pica_credit_add " +
+                        "and pica_credit_remove: it never replaces the set (that is " +
+                        "pica_credits_update) and never deletes-and-recreates, so the " +
+                        "credit keeps its id. Its attestation state is kept too, except " +
+                        "when person_id changes WHO it is for: a confirmed, disputed or " +
+                        "declined credit then goes back to pending, because the newly " +
+                        "linked person gave none of those answers (the response's " +
+                        "person_change says so). " +
+                        "Find the credit_id with pica_credits_list. " +
                         "Writer-split closure is NOT enforced on a single edit — re-split " +
                         "a song one writer at a time; the response's `allocation.status` " +
                         "(closed / open / incomplete) tells you whether the set still " +
@@ -715,6 +676,14 @@ export class CreditsTools {
                                 type: ["string", "null"],
                                 description: "Free-text notes. Pass null to clear.",
                             },
+                            person_id: {
+                                type: "string",
+                                description: "Change who this credit is for (UUID from pica_people_query) — link a name-only credit to a person record, or move a credit linked to the wrong person. The person must be in this organisation and not deleted; if they already hold this role on the song or recording, it is refused (CREDIT_PERSON_CONFLICT) rather than making a second credit. A confirmed, disputed or declined credit goes back to pending.",
+                            },
+                            confirm_name_mismatch: {
+                                type: "boolean",
+                                description: "Only with person_id on a name-only credit: set true after the user confirms the person is the one credited even though the names differ (e.g. a stage name). Without it a mismatch is refused (PERSON_NAME_MISMATCH).",
+                            },
                         },
                         required: ["work_id", "credit_id"],
                     },
@@ -799,19 +768,28 @@ export class CreditsTools {
                 credit_ids: creditIds,
                 reminder_type: reminderType,
             });
-            const delivered = (result.results || []).filter((r) => r.delivered);
-            const notPicaUsers = (result.results || []).filter((r) => r.reason === "not_a_pica_user");
-            const failed = (result.results || []).filter((r) => !r.delivered && r.reason !== "not_a_pica_user");
+            const rows = (result.results || []);
+            const name = (r) => r.person_name || r.person_id;
+            const of = (o) => rows.filter((r) => r.outcome === o);
+            const sent = of("sent");
+            const held = of("held");
+            const notPicaUsers = rows.filter((r) => r.outcome === "no_channel" && r.reason === "not_a_pica_user");
+            const noEmail = rows.filter((r) => r.outcome === "no_channel" && r.reason !== "not_a_pica_user");
+            const failed = of("failed");
             const summary = [
-                `Sent attestation prompt to ${delivered.length}/${result.results?.length ?? 0} credited people`,
-                delivered.length > 0
-                    ? `Delivered: ${delivered.map((r) => r.person_name || r.person_id).join(", ")}`
+                `Asked ${sent.length + held.length}/${rows.length} credited people`,
+                sent.length > 0 ? `Sent to: ${sent.map(name).join(", ")}` : null,
+                held.length > 0
+                    ? `Email held for approval (not delivered yet): ${held.map(name).join(", ")}`
                     : null,
                 notPicaUsers.length > 0
-                    ? `Not PICA users (use pica_collaborators_invite): ${notPicaUsers.map((r) => r.person_name || r.person_id).join(", ")}`
+                    ? `Not PICA users (use pica_collaborators_invite): ${notPicaUsers.map(name).join(", ")}`
+                    : null,
+                noEmail.length > 0
+                    ? `No email on file (add one to their person record): ${noEmail.map(name).join(", ")}`
                     : null,
                 failed.length > 0
-                    ? `Failed: ${failed.map((r) => r.person_name || r.person_id).join(", ")}`
+                    ? `Send failed: ${failed.map(name).join(", ")}`
                     : null,
             ]
                 .filter(Boolean)
@@ -819,6 +797,14 @@ export class CreditsTools {
             return formatSuccess(summary, result);
         }
         catch (err) {
+            // Nobody on the request could be reached: the route refuses with 422
+            // and names who and why. Not a transport failure.
+            const body = parseApiErrorBody(err);
+            if (body.code === "NO_REACHABLE_RECIPIENT") {
+                return typedError("NO_REACHABLE_RECIPIENT", body.message ?? "Nobody on this request could be reached.", body.details && typeof body.details === "object"
+                    ? body.details
+                    : undefined);
+            }
             const errorMessage = err instanceof Error ? err.message : String(err);
             return typedError("CREDITS_ATTESTATION_SEND_FAILED", `Failed to send credits for attestation: ${errorMessage}`);
         }
@@ -883,6 +869,26 @@ export class CreditsTools {
                 isError: true,
             };
         }
+        // attestation_status is not caller-settable. Since 2026-09-29 the
+        // collaborators route rejects it (UNKNOWN_FIELD) and
+        // replace_work_collaborators forces every inserted row to 'pending'
+        // (migration 20260929190000) — a caller could otherwise fabricate
+        // "attested" with no attestation ever happening. This tool kept
+        // advertising and forwarding it, so agents sent it and the whole write
+        // failed (ops 00d9e736, 9a1cb927). Refuse it here, before anything is
+        // written, with the way to actually get a credit confirmed — never
+        // silently drop it, or the caller believes the credit is attested.
+        const attestationIdx = args.credits
+            .map((c) => c ?? {})
+            .findIndex((c) => Object.hasOwn(c, "attestation_status"));
+        if (attestationIdx !== -1) {
+            return typedError("ATTESTATION_NOT_SETTABLE", `credits[${attestationIdx}] carries attestation_status, which this ` +
+                `tool can't set — nothing was saved. Every credit starts as ` +
+                `pending and only the credited person can confirm it. Remove ` +
+                `attestation_status from every entry and retry (put any source ` +
+                `evidence in notes), then call pica_credits_send_for_attestation ` +
+                `so each person can confirm their own credit.`, { field: "attestation_status", index: attestationIdx });
+        }
         // ADR-252: the 100% rule is a COMPOSITION concept (writer/publisher shares).
         // Master/recording credits carry independent, unconstrained splits (a
         // producer takes points; a vocalist may have 0%). Validate the total over
@@ -912,9 +918,9 @@ export class CreditsTools {
                 isError: true,
             };
         }
-        // ADR-252: only fields with a canonical home survive. is_primary,
-        // notes, attestation_status live on work_collaborators (composition);
-        // notes / attestation_status are also on recording_credits (master).
+        // ADR-252: only fields with a canonical home survive. is_primary and
+        // notes live on work_collaborators (composition); notes is also on
+        // recording_credits (master). attestation_status is refused above.
         // territory / rights_type / start_date / end_date / publisher_id /
         // publisher_split_percentage had no home after the work_credits drop and
         // are no longer accepted — see write-constants.ts.
@@ -933,8 +939,6 @@ export class CreditsTools {
                 credit.is_primary = c.is_primary;
             if (c.notes !== undefined)
                 credit.notes = c.notes;
-            if (c.attestation_status)
-                credit.attestation_status = c.attestation_status;
             return credit;
         });
         const publishingCredits = allCredits.filter((c) => PUBLISHING_ROLES.has(String(c.role || "writer")
@@ -1049,9 +1053,21 @@ export class CreditsTools {
      * is set, mirroring the work-side updateCredits notification flow.
      */
     async updateRecordingCredits(args) {
+        // attestation_status is not caller-settable. An attestation is the
+        // credited person confirming their credit; until 2026-10-03 this tool
+        // advertised it and the single form forwarded it, so any caller could
+        // create a master credit already "attested". The route now refuses it
+        // too, and session-role writes are refused in the database (migration
+        // 20261003072610). Refuse here, before anything is written, with the way
+        // to actually get a credit confirmed — never silently drop it, or the
+        // caller believes the credit is attested. Same code and shape as the
+        // pica_credits_update refusal in open PR #2622.
+        const attestationRefusal = refuseRecordingAttestation(args);
+        if (attestationRefusal)
+            return attestationRefusal;
         // Superset dispatch (write-merge fold, mirrors ReleasesTools.attachTrack)
-        // — subsumes pica_recording_credits_bulk_update. Both executors fully
-        // self-validate their own args; no other logic changes below.
+        // — subsumed pica_recording_credits_bulk_update (that name was removed in
+        // mcp-server 2.99.0). Both executors fully self-validate their own args.
         if (Array.isArray(args.credits)) {
             return this.bulkUpdateRecordingCredits(args);
         }
@@ -1104,11 +1120,6 @@ export class CreditsTools {
                 display_order: args.display_order ?? 0,
                 notes: args.notes ?? null,
                 instrument: args.instrument ?? null,
-                // ADR-252: master credits are attestable. The SDK input type predates
-                // the column; the route validates + persists it.
-                ...(args.attestation_status
-                    ? { attestation_status: args.attestation_status }
-                    : {}),
             });
         }
         catch (err) {
@@ -1176,7 +1187,10 @@ export class CreditsTools {
         return formatSuccess(msg, credit);
     }
     /**
-     * ADR-264 WS4 prerequisite — pica_recording_credits_bulk_update executor.
+     * ADR-264 WS4 prerequisite — the bulk path of pica_recording_credits_update
+     * (reached when args.credits is an array). It was also the executor of the
+     * standalone pica_recording_credits_bulk_update tool until mcp-server 2.99.0
+     * removed that name.
      *
      * Thin wrapper over POST /admin/recording-credits/bulk via
      * RecordingCreditsResource.bulkUpdate. The route + service own validation
@@ -1275,12 +1289,21 @@ export class CreditsTools {
             }
             patch.share_pct = v;
         }
-        for (const key of ["credit_type", "credited_name", "notes", "instrument"]) {
+        for (const key of [
+            "credit_type",
+            "credited_name",
+            "notes",
+            "instrument",
+            "person_id",
+        ]) {
             if (args[key] !== undefined)
                 patch[key] = args[key];
         }
         if (Object.keys(patch).length === 0) {
-            return typedError("VALIDATION_ERROR", "nothing to update — pass at least one of share_pct, credit_type, credited_name, notes, instrument.");
+            return typedError("VALIDATION_ERROR", "nothing to update — pass at least one of share_pct, credit_type, credited_name, notes, instrument, person_id.");
+        }
+        if (args.confirm_name_mismatch === true) {
+            patch.confirm_name_mismatch = true;
         }
         try {
             const result = await this.pica.credits.atomicUpdate(workId, creditId, patch);
@@ -1300,11 +1323,35 @@ export class CreditsTools {
                     severity: "important",
                 });
             }
+            const personChange = result?.person_change;
+            if (personChange?.attestation_reset) {
+                // person_change.message is the server's own sentence
+                // (describeCreditPersonChange in lib/services/credit-person-link.ts),
+                // so the agent hears the same account the routes give.
+                const what = personChange.message ??
+                    `This credit's ${personChange.previous_attestation_status ?? "previous"} status was cleared; it is now ${personChange.attestation_status ?? "pending"}.`;
+                hints.push({
+                    gap: "credit_confirmation_reset",
+                    suggestion: `${what} The person now linked gave no confirmation of their own. Tell the user, and offer to ask the newly linked person to confirm (pica_credits_send_for_attestation on this work).`,
+                    severity: "important",
+                });
+            }
             return formatSuccess("Credit updated", result, hints);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             const body = parseApiErrorBody(err);
+            // Typed refusals of a change of person (lib/services/credit-person-link.ts).
+            // Checked before the generic status branches: PERSON_NOT_FOUND is a
+            // 404 and CREDIT_PERSON_CONFLICT a 409, and each needs its own next step.
+            if (body.code === "PERSON_NOT_FOUND" ||
+                body.code === "PERSON_DELETED" ||
+                body.code === "PERSON_REQUIRED" ||
+                body.code === "PERSON_NAME_MISMATCH" ||
+                body.code === "CREDIT_PERSON_CONFLICT" ||
+                body.code === "PERSON_LINK_IS_THE_CATALOGUES") {
+                return typedError(body.code, body.message ?? message, body.details ?? undefined);
+            }
             if (body.code === "INSUFFICIENT_SCOPE" || body.status === 403) {
                 return typedError("INSUFFICIENT_SCOPE", `credit_id '${creditId}' is not a credit on work '${workId}' in this organisation. List the work's credits with pica_credits_list to find a valid id. Underlying error: ${message}`);
             }
@@ -1359,7 +1406,7 @@ export class CreditsTools {
                 content: [
                     {
                         type: "text",
-                        text: "share_pct must be a number between 0 and 100.",
+                        text: "share_pct must be a number between 0 and 100, or null (unknown).",
                     },
                 ],
                 isError: true,
@@ -1439,6 +1486,26 @@ export class CreditsTools {
             const existing = recordingCreditExists(err);
             if (existing)
                 return existing;
+            // A 4xx carrying a machine code is the route REFUSING this call for a
+            // reason it names (VALIDATION_ERROR, PERSON_ORG_MISMATCH,
+            // RECORDING_TARGET_REQUIRED, SHARES_ARE_SUGGESTIONS, …). Relay that
+            // code and message instead of folding it into CREDIT_ADD_FAILED, which
+            // reads as a transport failure and invites a blind retry — ops
+            // 704708a1 was a 400 VALIDATION_ERROR reported as CREDIT_ADD_FAILED.
+            const refusal = parseApiErrorBody(err);
+            if (refusal.code &&
+                refusal.status !== undefined &&
+                refusal.status >= 400 &&
+                refusal.status < 500) {
+                // Siblings first, so a route key can never overwrite the envelope's
+                // own `error` / `message` (typedError writes those last).
+                return typedError(refusal.code, refusal.message ?? errorMessage, {
+                    ...refusal.extra,
+                    ...(refusal.details !== undefined
+                        ? { details: refusal.details }
+                        : {}),
+                });
+            }
             return typedError("CREDIT_ADD_FAILED", `Failed to add credit: ${errorMessage}`);
         }
     }