@withpica/mcp-server 2.46.0 → 2.48.0

package/dist/tools/sync-placements.js

@@ -0,0 +1,431 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { formatAsText, formatList, formatSuccess } from "@withpica/mcp-utils";
+import { withBillingGate } from "@withpica/mcp-utils";
+export class SyncPlacementsTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_sync_placements_query",
+                    description: "List sync placements for the org. Filters: work_id, status, verification_status, brand, production_company, person_id, recording_id, source_license_enquiry_id, min_fee, currency. Returns up to `limit` (default 50) with cursor support via `offset`.",
+                    workflows: ["sync-placement-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            work_id: {
+                                type: "string",
+                                description: "Filter by work id",
+                            },
+                            status: {
+                                type: "string",
+                                enum: ["licensed", "aired", "expired", "renewed", "terminated"],
+                                description: "Filter by placement lifecycle status",
+                            },
+                            verification_status: {
+                                type: "string",
+                                enum: [
+                                    "unverified",
+                                    "self_attested",
+                                    "evidence_attached",
+                                    "operator_verified",
+                                    "disputed",
+                                ],
+                                description: "Filter by evidence verification state",
+                            },
+                            brand: {
+                                type: "string",
+                                description: "Filter by advertiser/brand name",
+                            },
+                            production_company: {
+                                type: "string",
+                                description: "Filter by production company name",
+                            },
+                            person_id: {
+                                type: "string",
+                                description: "Filter to placements where this person is a contact (music supervisor, etc.)",
+                            },
+                            recording_id: {
+                                type: "string",
+                                description: "Filter to placements that licensed this recording",
+                            },
+                            source_license_enquiry_id: {
+                                type: "string",
+                                description: "Filter to placements that originated from this license enquiry",
+                            },
+                            min_fee: {
+                                type: "number",
+                                description: "Minimum fee_amount (pre-pagination SQL filter)",
+                            },
+                            currency: {
+                                type: "string",
+                                description: "ISO-4217 currency code (e.g. USD, GBP)",
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Max results (default 50)",
+                            },
+                            offset: {
+                                type: "number",
+                                description: "Cursor offset",
+                            },
+                        },
+                    },
+                },
+                executor: this.query.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_sync_placements_inspect",
+                    description: "Get one sync placement by id, including all linked recordings, evidence sources, the underlying agreement, and party rows.",
+                    workflows: ["sync-placement-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Sync placement id",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: this.inspect.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_sync_placements_create",
+                    description: "Create a sync placement (atomic — placement + draft sync_license agreement + at least one agreement_party + recordings + evidence sources, all in one Postgres transaction). Requires at least one entry in `contacts[]`. Empty contacts rejects with structured MISSING_CONTACT (next_tool: pica_people_query). New people can be auto-created inline by passing `person_name` instead of `person_id`.",
+                    workflows: ["sync-placement-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            work_id: {
+                                type: "string",
+                                description: "Work being licensed for the placement",
+                            },
+                            production_title: {
+                                type: "string",
+                                description: "The film/series/ad/game name the work is licensed into",
+                            },
+                            production_type: {
+                                type: "string",
+                                description: "Film, TV, advertising, trailer, video game, etc.",
+                            },
+                            brand: {
+                                type: "string",
+                                description: "Advertiser brand (for ad placements)",
+                            },
+                            production_company: {
+                                type: "string",
+                                description: "Production company name",
+                            },
+                            status: {
+                                type: "string",
+                                enum: ["licensed", "aired", "expired", "renewed", "terminated"],
+                                description: "Initial status (default 'licensed')",
+                            },
+                            fee_amount: {
+                                type: "number",
+                                description: "Total fee in minor units of fee_currency",
+                            },
+                            fee_currency: {
+                                type: "string",
+                                description: "ISO-4217 currency code",
+                            },
+                            use_start_date: {
+                                type: "string",
+                                description: "ISO-8601 date — first day of licensed use",
+                            },
+                            use_end_date: {
+                                type: "string",
+                                description: "ISO-8601 date — last day of licensed use",
+                            },
+                            territory: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "ISO-3166 country codes; ['WW'] = worldwide",
+                            },
+                            media_channels: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "tv, online, theatrical, social, in-game, in-store, etc.",
+                            },
+                            notes: {
+                                type: "string",
+                                description: "Free-text notes",
+                            },
+                            confidentiality_level: {
+                                type: "string",
+                                enum: ["public", "redacted_in_public_car", "private"],
+                                description: "Public-CAR redaction policy (default 'redacted_in_public_car')",
+                            },
+                            contacts: {
+                                type: "array",
+                                description: "At least one contact required. Pass `person_id` for an existing person OR `person_name` (+ optional email/company/position) to auto-create.",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        person_id: { type: "string" },
+                                        person_name: { type: "string" },
+                                        role: {
+                                            type: "string",
+                                            description: "music_supervisor | brand_marketing_lead | sync_agent | clearance_attorney | film_producer | director | …",
+                                        },
+                                        email: { type: "string" },
+                                        company: { type: "string" },
+                                        position: { type: "string" },
+                                        split_percentage: {
+                                            type: "number",
+                                            description: "Optional commission split (0–100)",
+                                        },
+                                    },
+                                    required: ["role"],
+                                },
+                                minItems: 1,
+                            },
+                            recordings: {
+                                type: "array",
+                                description: "Specific recordings being licensed under the placement (optional but typical for sync — one master per recording).",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        recording_id: { type: "string" },
+                                        role: {
+                                            type: "string",
+                                            description: "main_master | re_record | instrumental | edit | trailer_cut | …",
+                                        },
+                                        master_fee: { type: "number" },
+                                        master_share_licensed_pct: { type: "number" },
+                                        notes: { type: "string" },
+                                    },
+                                    required: ["recording_id", "role"],
+                                },
+                            },
+                            sources: {
+                                type: "array",
+                                description: "Evidence sources backing the placement. Auto-advances verification_status: any 'cue_sheet'/'invoice'/'agreement_pdf'/'email'/'screenshot'/'web'/'spreadsheet_import' → evidence_attached; 'user_attestation' only → self_attested; none → unverified.",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        url: { type: "string" },
+                                        kind: {
+                                            type: "string",
+                                            enum: [
+                                                "user_attestation",
+                                                "agreement_pdf",
+                                                "cue_sheet",
+                                                "invoice",
+                                                "email",
+                                                "screenshot",
+                                                "web",
+                                                "spreadsheet_import",
+                                            ],
+                                        },
+                                        agent_id: { type: "string" },
+                                        field_coverage: {
+                                            type: "array",
+                                            items: { type: "string" },
+                                        },
+                                        notes: { type: "string" },
+                                    },
+                                    required: ["url", "kind"],
+                                },
+                            },
+                        },
+                        required: ["work_id", "production_title", "contacts"],
+                    },
+                },
+                executor: withBillingGate(this.pica, "sync placement creation", this.create.bind(this)),
+            },
+            {
+                definition: {
+                    name: "pica_sync_placements_update",
+                    description: "Patch a sync placement. Most fields are unconditional; `verification_status` (when set to 'operator_verified' or 'disputed') and `confidentiality_level` are operator-gated and will throw OPERATOR_REQUIRED for customer agents — use a soft transition like status:'terminated' for self-service retirement instead. Status transitions follow the placement state machine; illegal transitions throw INVALID_TRANSITION (inspect first to see the current state).",
+                    workflows: ["sync-placement-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Sync placement id",
+                            },
+                            status: {
+                                type: "string",
+                                enum: ["licensed", "aired", "expired", "renewed", "terminated"],
+                                description: "Placement lifecycle status — transitions follow the sync_placement_status state machine; setting status:'terminated' is the customer-facing soft-delete path.",
+                            },
+                            verification_status: {
+                                type: "string",
+                                enum: [
+                                    "unverified",
+                                    "self_attested",
+                                    "evidence_attached",
+                                    "operator_verified",
+                                    "disputed",
+                                ],
+                                description: "Evidence verification state. Operator-only when set to 'operator_verified' or 'disputed'; other values throw OPERATOR_REQUIRED for customer agents.",
+                            },
+                            confidentiality_level: {
+                                type: "string",
+                                enum: ["public", "redacted_in_public_car", "private"],
+                                description: "Public-CAR redaction policy. Operator-only — changing this throws OPERATOR_REQUIRED for customer agents.",
+                            },
+                            production_title: {
+                                type: "string",
+                                description: "The film/series/ad/game name the work is licensed into",
+                            },
+                            production_type: {
+                                type: "string",
+                                description: "Film, TV, advertising, trailer, video game, etc.",
+                            },
+                            brand: {
+                                type: "string",
+                                description: "Advertiser brand (for ad placements)",
+                            },
+                            production_company: {
+                                type: "string",
+                                description: "Production company name",
+                            },
+                            fee_amount: {
+                                type: "number",
+                                description: "Total fee in minor units of fee_currency",
+                            },
+                            fee_currency: {
+                                type: "string",
+                                description: "ISO-4217 currency code",
+                            },
+                            use_start_date: {
+                                type: "string",
+                                description: "ISO-8601 date — first day of licensed use",
+                            },
+                            use_end_date: {
+                                type: "string",
+                                description: "ISO-8601 date — last day of licensed use",
+                            },
+                            territory: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "ISO-3166 country codes; ['WW'] = worldwide",
+                            },
+                            media_channels: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "tv, online, theatrical, social, in-game, in-store, etc.",
+                            },
+                            notes: {
+                                type: "string",
+                                description: "Free-text notes",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: withBillingGate(this.pica, "sync placement update", this.update.bind(this)),
+            },
+            {
+                definition: {
+                    name: "pica_sync_placements_delete",
+                    description: "Hard-delete a sync placement. Operator-only — customer agents will receive structured OPERATOR_REQUIRED. For self-service retirement, use pica_sync_placements_update with status:'terminated' (soft-delete). Two-step confirmation pattern: first call returns a confirmation_token; second call with the token executes the delete.",
+                    workflows: ["sync-placement-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Sync placement id",
+                            },
+                            confirmation_token: {
+                                type: "string",
+                                description: "Token from a prior call; required to actually execute the delete",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: withBillingGate(this.pica, "sync placement deletion", this.delete.bind(this)),
+            },
+            {
+                definition: {
+                    name: "pica_sync_placements_cite",
+                    description: "Attach an evidence source to a sync placement. Auto-recomputes verification_status — any non-attestation kind ('cue_sheet'/'invoice'/'agreement_pdf'/'email'/'screenshot'/'web'/'spreadsheet_import') advances unverified/self_attested → evidence_attached. operator_verified is sticky (only an explicit operator action exits it).",
+                    workflows: ["sync-placement-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Sync placement id",
+                            },
+                            url: {
+                                type: "string",
+                                description: "Evidence URL",
+                            },
+                            kind: {
+                                type: "string",
+                                enum: [
+                                    "user_attestation",
+                                    "agreement_pdf",
+                                    "cue_sheet",
+                                    "invoice",
+                                    "email",
+                                    "screenshot",
+                                    "web",
+                                    "spreadsheet_import",
+                                ],
+                                description: "Source kind. Any non-attestation kind advances verification_status to evidence_attached on first attach.",
+                            },
+                            agent_id: {
+                                type: "string",
+                                description: "Optional agent identity that supplied the source",
+                            },
+                            field_coverage: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Which placement fields this source attests to (used for evidence attribution in exports)",
+                            },
+                            notes: {
+                                type: "string",
+                                description: "Free-text notes",
+                            },
+                        },
+                        required: ["id", "url", "kind"],
+                    },
+                },
+                executor: withBillingGate(this.pica, "sync placement evidence", this.cite.bind(this)),
+            },
+        ];
+    }
+    // ── executors ──────────────────────────────────────────────────────────
+    async query(args) {
+        const result = await this.pica.syncPlacements.list(args);
+        return formatList(result.data, { total: result.total });
+    }
+    async inspect(args) {
+        const placement = await this.pica.syncPlacements.get(args.id);
+        return formatAsText(placement);
+    }
+    async create(args) {
+        const placement = await this.pica.syncPlacements.create(args);
+        return formatSuccess("Sync placement created", placement);
+    }
+    async update(args) {
+        const { id, ...patch } = args;
+        const placement = await this.pica.syncPlacements.update(id, patch);
+        return formatSuccess("Sync placement updated", placement);
+    }
+    async delete(args) {
+        const { id, confirmation_token } = args;
+        await this.pica.syncPlacements.delete(id, { confirmation_token });
+        return formatSuccess(`Sync placement ${id} deleted`);
+    }
+    async cite(args) {
+        const { id, ...source } = args;
+        const result = await this.pica.syncPlacements.addSource(id, source);
+        return formatSuccess("Evidence attached to sync placement", result);
+    }
+}
+//# sourceMappingURL=sync-placements.js.map

package/dist/tools/sync-placements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-placements.js","sourceRoot":"","sources":["../../src/tools/sync-placements.ts"],"names":[],"mappings":"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"}

package/dist/tools/works.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"works.d.ts","sourceRoot":"","sources":["../../src/tools/works.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAWtE;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkHzE,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B;;OAEG;IACH,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;IA8PzE;;OAEG;YACW,UAAU;IAsDxB;;OAEG;YACW,WAAW;IAsNzB;;OAEG;YACW,UAAU;IAkCxB;;OAEG;YACW,UAAU;IAMxB;;OAEG;YACW,UAAU;IAKxB;;OAEG;YACW,UAAU;IAiDxB;;OAEG;YACW,eAAe;CAM9B"}
+{"version":3,"file":"works.d.ts","sourceRoot":"","sources":["../../src/tools/works.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAatE;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkHzE,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B;;OAEG;IACH,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;IA8PzE;;OAEG;YACW,UAAU;IAsDxB;;OAEG;YACW,WAAW;IAwPzB;;OAEG;YACW,UAAU;IAkCxB;;OAEG;YACW,UAAU;IAMxB;;OAEG;YACW,UAAU;IAKxB;;OAEG;YACW,UAAU;IAiDxB;;OAEG;YACW,eAAe;CAM9B"}

package/dist/tools/works.js

@@ -1,5 +1,5 @@
 // Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
-import { formatSuccess, formatStructuredList, withBillingGate, mapGapsToHints, } from "@withpica/mcp-utils";
+import { formatSuccess, formatStructuredList, withBillingGate, mapGapsToHints, pushSectionError, } from "@withpica/mcp-utils";
 import { buildCustodyHints } from "./custody-hints.js";
 import { computeWorkGapHints } from "./gap-hints.js";
 /**
@@ -32,7 +32,7 @@ export const WORK_WRITE_PROPERTIES = {
     },
     isrc: {
         type: "string",
-        description: "International Standard Recording Code. Bridges publishing (works) and masters (recordings). ADR-165 Phase 5 will move this to recordings; for now still settable on works.",
+        description: "International Standard Recording Code. Bridges publishing (works) and masters (recordings).",
     },
     tunecode: {
         type: "string",
@@ -44,7 +44,7 @@ export const WORK_WRITE_PROPERTIES = {
     },
     spotify_track_uri: {
         type: "string",
-        description: "Spotify track URI (e.g. spotify:track:0b8ZtRm9u3xSzRazABeHFF). ADR-165 Phase 5 will move this to recordings.",
+        description: "Spotify track URI (e.g. spotify:track:0b8ZtRm9u3xSzRazABeHFF).",
     },
     duration_seconds: {
         type: "number",
@@ -168,7 +168,7 @@ export class WorksTools {
                     name: "pica_works_inspect",
                     description: "Get details and quality data for a specific work. Omit sections for everything. " +
                         "Use sections=['enrichment'] to see cascade provenance (which source wrote each field), " +
-                        "completeness_score, completeness_breakdown, AND live enrichment-job statuses (spotify/mlc/acrcloud/railway) " +
+                        "completeness_score, completeness_breakdown, AND live enrichment-job statuses (spotify, mlc, acrcloud, audio analysis) " +
                         "in one response. " +
                         "→ then: pica_credits_update (fix credits), pica_resolve_work (fill identifiers + metadata), pica_run_work_cascade (retry)",
                     workflows: "infrastructure",
@@ -282,7 +282,7 @@ export class WorksTools {
                     nextSteps: [
                         {
                             tool: "pica_works_inspect",
-                            reason: "Read back the work after update to confirm every field round-tripped (ADR-198 sister check).",
+                            reason: "Read back the work after update to confirm every field round-tripped — silent persistence drops are real.",
                             when: "on_success",
                         },
                     ],
@@ -411,6 +411,16 @@ export class WorksTools {
         const has = (s) => allSections ? !ORG_WIDE_OPT_IN.has(s) : sections.includes(s);
         const result = {};
         const hints = [];
+        // ADR-224 — section-level failures push to errors[] and the host
+        // log pipeline (via pushSectionError) regardless of flag state.
+        // The flag controls whether the public response advertises errors[]
+        // and whether failed sections set the field to null vs the legacy
+        // empty-fallback. Default OFF in Phase 1; flips to default-on at
+        // Phase 4 after the soak window catches any caller depending on
+        // the empty-array shape.
+        const useStructured = process.env.ADR_224_STRUCTURED_ERRORS === "1";
+        const errors = [];
+        const TOOL_NAME = "pica_works_inspect";
         // Basic — always fetched (either via entityContext.getWorkFull or works.get)
         if (allSections) {
             const full = await this.pica.entityContext.getWorkFull(args.id);
@@ -447,8 +457,9 @@ export class WorksTools {
                     try {
                         result.credits = await this.pica.credits.listForWork(args.id);
                     }
-                    catch {
-                        result.credits = [];
+                    catch (e) {
+                        result.credits = useStructured ? null : [];
+                        pushSectionError(errors, TOOL_NAME, "credits", e, args.id);
                     }
                 })());
             }
@@ -457,8 +468,9 @@ export class WorksTools {
                     try {
                         result.recordings = await this.pica.recordings.getByWork(args.id);
                     }
-                    catch {
-                        result.recordings = [];
+                    catch (e) {
+                        result.recordings = useStructured ? null : [];
+                        pushSectionError(errors, TOOL_NAME, "recordings", e, args.id);
                     }
                 })());
             }
@@ -467,8 +479,9 @@ export class WorksTools {
                     try {
                         result.agreements = await this.pica.agreements.list();
                     }
-                    catch {
-                        result.agreements = [];
+                    catch (e) {
+                        result.agreements = useStructured ? null : [];
+                        pushSectionError(errors, TOOL_NAME, "agreements", e, args.id);
                     }
                 })());
             }
@@ -479,8 +492,9 @@ export class WorksTools {
                 try {
                     result.health = await this.pica.health.getWorksHealth();
                 }
-                catch {
+                catch (e) {
                     result.health = null;
+                    pushSectionError(errors, TOOL_NAME, "health", e, args.id);
                 }
             })());
         }
@@ -491,8 +505,9 @@ export class WorksTools {
                     result.completeness = completeness;
                     hints.push(...mapGapsToHints(completeness?.gaps || completeness?.missing || []));
                 }
-                catch {
+                catch (e) {
                     result.completeness = null;
+                    pushSectionError(errors, TOOL_NAME, "completeness", e, args.id);
                 }
             })());
         }
@@ -502,8 +517,9 @@ export class WorksTools {
                     result.registration =
                         await this.pica.registration.getWorkCascadeStatus(args.id);
                 }
-                catch {
+                catch (e) {
                     result.registration = null;
+                    pushSectionError(errors, TOOL_NAME, "registration", e, args.id);
                 }
             })());
         }
@@ -512,8 +528,9 @@ export class WorksTools {
                 try {
                     result.score = await this.pica.picaScore.get();
                 }
-                catch {
+                catch (e) {
                     result.score = null;
+                    pushSectionError(errors, TOOL_NAME, "score", e, args.id);
                 }
             })());
         }
@@ -522,8 +539,9 @@ export class WorksTools {
                 try {
                     result.provenance = await this.pica.analytics.provenanceWork(args.id);
                 }
-                catch {
+                catch (e) {
                     result.provenance = null;
+                    pushSectionError(errors, TOOL_NAME, "provenance", e, args.id);
                 }
             })());
         }
@@ -533,8 +551,9 @@ export class WorksTools {
                     result.enrichment =
                         await this.pica.enrichment.getWorkEnrichmentStatus(args.id);
                 }
-                catch {
+                catch (e) {
                     result.enrichment = null;
+                    pushSectionError(errors, TOOL_NAME, "enrichment", e, args.id);
                 }
             })());
         }
@@ -546,8 +565,9 @@ export class WorksTools {
                     result.production_assets =
                         await this.pica.works.listProductionAssets(args.id);
                 }
-                catch {
-                    result.production_assets = [];
+                catch (e) {
+                    result.production_assets = useStructured ? null : [];
+                    pushSectionError(errors, TOOL_NAME, "production_assets", e, args.id);
                 }
             })());
         }
@@ -559,8 +579,9 @@ export class WorksTools {
                 try {
                     result.releases = await this.pica.works.listReleases(args.id);
                 }
-                catch {
-                    result.releases = [];
+                catch (e) {
+                    result.releases = useStructured ? null : [];
+                    pushSectionError(errors, TOOL_NAME, "releases", e, args.id);
                 }
             })());
         }
@@ -568,7 +589,14 @@ export class WorksTools {
         // ADR-193 Surface 2 — proactive peer-MCP hints when the flag is on
         // and a real gap exists. Additive on top of the CompletionHint path.
         const gap_hints = computeWorkGapHints(result);
-        const enriched = gap_hints.length > 0 ? { ...result, gap_hints } : result;
+        const withHints = gap_hints.length > 0 ? { ...result, gap_hints } : result;
+        // ADR-224 — append errors[] to the public response only when the
+        // structured-errors flag is on. In legacy mode, section failures are
+        // still pushed to the errors[] array (so stderr observability fires
+        // via pushSectionError) but the array is dropped from the response
+        // shape so the breaking change ([] → null on failed sections) doesn't
+        // ship until Phase 4's flip.
+        const enriched = useStructured ? { ...withHints, errors } : withHints;
         return formatSuccess(`Work details${sections ? ` (sections: ${sections.join(", ")})` : ""}`, enriched, hints);
     }
     /**