monday-cli 0.5.0 → 0.7.0

package/dist/commands/item/update.js

@@ -52,13 +52,18 @@ import { parseArgv } from '../parse-argv.js';
 import { ApiError, MondayCliError, UsageError } from '../../utils/errors.js';
 import { selectMutation, } from '../../api/column-values.js';
 import { executeItemMutation } from '../../api/item-mutation-execute.js';
+import { executeFileColumnSet, fileColumnSetOutputSchema, preCheckM38FileDispatch, } from '../../api/file-column-set.js';
+import { precheckLocalFile } from '../../utils/file-source.js';
+import { invalidateBoard } from '../../api/cache.js';
+import { dispatchSequential, } from '../../api/partial-success-mutation.js';
+import { dispatchParallel } from '../../api/parallel-dispatch.js';
 import { parseSetRawExpression, } from '../../api/raw-write.js';
 import { splitSetExpression } from '../../api/set-expression.js';
 import { buildResolutionContexts } from '../../api/resolution-context.js';
 import { resolveBoardId } from '../../api/item-board-lookup.js';
-import { SourceAggregator } from '../../api/source-aggregator.js';
+import { SourceAggregator, mergeCacheAge, mergeSource, } from '../../api/source-aggregator.js';
 import { resolveAndTranslate } from '../../api/resolution-pass.js';
-import { foldAndRemap } from '../../api/resolver-error-fold.js';
+import { foldAndRemap, mergeResolverWarningsIntoError, } from '../../api/resolver-error-fold.js';
 import { planChanges } from '../../api/dry-run.js';
 import { buildQueryParams } from '../../api/filters.js';
 import { loadBoardMetadata, refreshBoardMetadata, } from '../../api/board-metadata.js';
@@ -69,7 +74,23 @@ import { resolveMeFactory } from '../../api/item-helpers.js';
 import { projectedItemSchema, } from '../../api/item-projection.js';
 import { runPartialSuccessBulkUpdate, buildPartialSuccessBulkSummary, partialSuccessBulkUpdateDataSchema, PARTIAL_SUCCESS_BULK_DISPATCH_SOURCE, } from '../../api/partial-success-bulk.js';
 import { MIN_CONCURRENCY, MAX_CONCURRENCY, } from '../../api/parallel-dispatch.js';
-export const itemUpdateOutputSchema = projectedItemSchema;
+/**
+ * Output envelope union — projected-item for the JSON translator
+ * path (text / status / dropdown / date / people / etc.) +
+ * file-dispatch envelope for the friendly `--set <file-col>=<path>`
+ * path. The file-dispatch shape ships across v0.6-M38 (single-item
+ * — `operation: 'add_file_to_column'`) and v0.7-M42 (bulk —
+ * `operation: 'item_update_bulk_file_set'`; the per-item fan-out's
+ * `data.results[i].asset` slots wrap M31's `Asset` projection). The
+ * union below admits only the single-item shape because the bulk
+ * variant is emitted via its own `bulkFileSetDataSchema` at the
+ * `runItemUpdateBulkFileDispatch` helper; agents discriminate on
+ * `operation` (present + literal value identifies the variant).
+ */
+export const itemUpdateOutputSchema = z.union([
+    projectedItemSchema,
+    fileColumnSetOutputSchema,
+]);
 /**
  * Input shape — supports both single-item and bulk shapes.
  *
@@ -256,7 +277,7 @@ export const itemUpdateCommand = {
                 ...(itemId === undefined ? {} : { itemId }),
                 ...opts,
             });
-            const { client, globalFlags, apiVersion, toEmit } = resolveClient(ctx, program.opts());
+            const { client, globalFlags, apiVersion, multipart, toEmit } = resolveClient(ctx, program.opts());
             const dispatch = validateInputShape(parsed);
             if (dispatch.kind === 'bulk') {
                 await runBulk({
@@ -266,6 +287,7 @@ export const itemUpdateCommand = {
                     apiVersion,
                     ctx,
                     programOpts: program.opts(),
+                    multipart,
                 });
                 return;
             }
@@ -284,49 +306,150 @@ export const itemUpdateCommand = {
                 explicit: parsed.board,
             });
             const { dateResolution, peopleResolution, tagResolution, relationResolution } = buildResolutionContexts({ client, ctx, globalFlags });
-            if (globalFlags.dryRun) {
-                const result = await planChanges({
+            // v0.6-M38 mutex check at the column-resolution boundary
+            // (cli-design §5.3 step 5 "File-column dispatch leg —
+            // mutex rules"; D2/D5/D6 closures). Pre-checks setEntries'
+            // column types BEFORE calling `planChanges` /
+            // `resolveAndTranslate`, so the mutex rules fire upfront
+            // independent of translator-order side effects. The
+            // pre-check operates on setEntries only — `--set-raw
+            // <file-col>=<json>` rejection stays at
+            // `translateRawColumnValue` per D3 (permanent rejection;
+            // M38 dispatch never hijacks the --set-raw path).
+            const m38 = await preCheckM38FileDispatch({
+                client,
+                boardId,
+                setEntries,
+                setRawCount: rawEntries.length,
+                hasName: parsed.name !== undefined,
+                callShape: 'item_update_single',
+                env: ctx.env,
+                noCache: globalFlags.noCache,
+            });
+            if (m38.kind === 'file') {
+                // M38 dispatch path. The dry-run / live branches emit the
+                // D4 envelope / M31-shaped envelope respectively, threading
+                // the pre-check's resolver warnings + source aggregation
+                // into the final envelope (P3-1 — IMPL round-1 fix).
+                await runItemUpdateSingleFileDispatch({
                     client,
+                    multipart,
+                    ctx,
+                    programOpts: program.opts(),
+                    apiVersion,
                     boardId,
                     itemId: dispatch.itemId,
-                    setEntries,
-                    ...(rawEntries.length === 0 ? {} : { rawEntries }),
-                    ...(parsed.name === undefined ? {} : { nameChange: parsed.name }),
-                    dateResolution,
-                    peopleResolution,
-                    tagResolution,
-                    relationResolution,
-                    env: ctx.env,
-                    noCache: globalFlags.noCache,
+                    m38,
+                    isDryRun: globalFlags.dryRun,
+                    retries: globalFlags.retry,
+                    toEmit,
                 });
+                return;
+            }
+            if (globalFlags.dryRun) {
+                // m38.kind === 'json' — standard JSON translator path
+                // applies. The pre-check's resolver warnings + source
+                // aggregation seed the downstream planChanges run
+                // (downstream resolveAndTranslate hits cache for the
+                // already-resolved setEntries; source aggregation is
+                // correct per §6.1 — both legs counted).
+                let result;
+                try {
+                    result = await planChanges({
+                        client,
+                        boardId,
+                        itemId: dispatch.itemId,
+                        setEntries,
+                        ...(rawEntries.length === 0 ? {} : { rawEntries }),
+                        ...(parsed.name === undefined ? {} : { nameChange: parsed.name }),
+                        dateResolution,
+                        peopleResolution,
+                        tagResolution,
+                        relationResolution,
+                        env: ctx.env,
+                        noCache: globalFlags.noCache,
+                    });
+                }
+                catch (err) {
+                    // Round-3 P3-1 fix: fold M38 pre-check warnings into
+                    // the failure envelope's `details.resolver_warnings`
+                    // slot. The pre-check may have emitted
+                    // `stale_cache_refreshed` / `column_token_collision`;
+                    // if downstream `planChanges` throws (translator
+                    // error, archived column, etc.), the error's own
+                    // fold doesn't include the pre-check leg.
+                    if (err instanceof MondayCliError && m38.warnings.length > 0) {
+                        throw mergeResolverWarningsIntoError(err, m38.warnings);
+                    }
+                    throw err;
+                }
+                // Round-2 P3-1 fix: thread the pre-check's resolver
+                // warnings into the dry-run envelope. A
+                // `stale_cache_refreshed` or `column_token_collision`
+                // emitted by the pre-check would otherwise be lost —
+                // downstream `planChanges` re-resolves against the
+                // now-warm cache and doesn't re-emit `stale_cache_refreshed`
+                // (the refresh already ran). Dedupe by code+message+token
+                // mirrors `dedupeWarnings` from the bulk path.
+                //
+                // **Round-3 P3-1 fix (error-path)**: the planChanges
+                // call itself is wrapped above (line 483); if it throws
+                // before returning, the error catch below folds
+                // `m38.warnings` into `details.resolver_warnings` so
+                // pre-check warnings ride into the failure envelope
+                // too.
                 emitDryRun({
                     ctx,
                     programOpts: program.opts(),
                     plannedChanges: result.plannedChanges,
-                    source: result.source,
-                    cacheAgeSeconds: result.cacheAgeSeconds,
-                    warnings: result.warnings,
+                    source: mergeSource(m38.source, result.source),
+                    cacheAgeSeconds: mergeCacheAge(m38.cacheAgeSeconds, result.cacheAgeSeconds),
+                    warnings: dedupeWarnings([...m38.warnings, ...result.warnings]),
                     apiVersion,
                 });
                 return;
             }
             // Live update path — three-pass resolution + translation
-            // through the shared helper (R20 lift).
-            const resolutionResult = await resolveAndTranslate({
-                client,
-                boardId,
-                setEntries,
-                rawEntries,
-                dateResolution,
-                peopleResolution,
-                tagResolution,
-                relationResolution,
-                env: ctx.env,
-                noCache: globalFlags.noCache,
-            });
-            const collectedWarnings = [
+            // through the shared helper (R20 lift). Pre-check already
+            // resolved setEntries (cache hit downstream).
+            let resolutionResult;
+            try {
+                resolutionResult = await resolveAndTranslate({
+                    client,
+                    boardId,
+                    setEntries,
+                    rawEntries,
+                    dateResolution,
+                    peopleResolution,
+                    tagResolution,
+                    relationResolution,
+                    env: ctx.env,
+                    noCache: globalFlags.noCache,
+                    ...(m38.source === undefined ? {} : { initialSource: m38.source }),
+                    initialCacheAgeSeconds: m38.cacheAgeSeconds,
+                });
+            }
+            catch (err) {
+                // Round-3 P3-1 fix: fold M38 pre-check warnings into the
+                // failure envelope's `details.resolver_warnings` slot. The
+                // pre-check may have emitted `stale_cache_refreshed` /
+                // `column_token_collision`; if downstream
+                // `resolveAndTranslate` throws (translator error, archived
+                // column post-cache-warm, etc.), the thrown error's own
+                // resolver-warnings fold doesn't include the pre-check leg.
+                if (err instanceof MondayCliError && m38.warnings.length > 0) {
+                    throw mergeResolverWarningsIntoError(err, m38.warnings);
+                }
+                throw err;
+            }
+            // Round-2 P3-1 fix: thread pre-check's resolver warnings
+            // alongside downstream warnings, deduped by code+message+
+            // token — pre-check's `stale_cache_refreshed` would
+            // otherwise be lost (warm cache suppresses re-emit).
+            const collectedWarnings = dedupeWarnings([
+                ...m38.warnings,
                 ...resolutionResult.warnings,
-            ];
+            ]);
             const resolvedIds = resolutionResult.resolvedIds;
             const sourceAgg = new SourceAggregator();
             if (resolutionResult.source !== undefined) {
@@ -489,7 +612,7 @@ const bulkLiveDataSchema = z.object({
  * `--concurrency` flag is the future extension point.
  */
 const runBulk = async (inputs) => {
-    const { parsed, client, globalFlags, apiVersion, ctx, programOpts } = inputs;
+    const { parsed, client, globalFlags, apiVersion, ctx, programOpts, multipart } = inputs;
     /* c8 ignore next 6 — defensive: validateInputShape guarantees
        parsed.board is non-undefined when shape is bulk; the type
        guard exists for TS. */
@@ -514,6 +637,63 @@ const runBulk = async (inputs) => {
         env: ctx.env,
         noCache: globalFlags.noCache,
     });
+    // 1.5) File-column dispatch pre-check at the column-resolution
+    //      boundary, BEFORE the items_page walker + confirmation
+    //      gate. The pre-check resolves setEntries against the now-
+    //      warm metadata cache and runs
+    //      `enforceSingleFileColumnSet({callShape: 'item_update_bulk'})`:
+    //
+    //        - Multi-file `--set` → throws `'multi_file_set_unsupported'`
+    //          (universal rule; single-column-per-wire-call).
+    //        - File `--set` + value `--set` / `--set-raw` / `--name`
+    //          → throws `'mixed_file_and_value_sets'` (universal rule;
+    //          mixing forces non-atomic multi-leg dispatch).
+    //        - Clean single file `--set` → returns
+    //          `kind: 'file_bulk'` (v0.7-M42 D5 carve-out fold;
+    //          action body branches into the per-item multipart
+    //          fan-out helper `runItemUpdateBulkFileDispatch` —
+    //          shipped at v0.7-M42 IMPL).
+    //        - No file `--set` → returns `kind: 'json'` (standard
+    //          JSON-translator path continues).
+    //
+    //      At v0.6-M38 the `'item_update_bulk'` callShape rejected
+    //      ALL bulk file `--set` paths with
+    //      `'file_set_on_bulk_unsupported'`; v0.7-M42 pre-flight
+    //      contract diff (`160330b`) carved that out per D5 fold,
+    //      and IMPL (`22df2fa` + R1 fix-up `968b154`) shipped the
+    //      runtime body. `--set-raw <file-col>=<json>` stays at
+    //      `translateRawColumnValue`'s D3 permanent rejection (the
+    //      pre-check only inspects setEntries; the standard path's
+    //      `translateRawColumnValue` handles --set-raw rejection
+    //      unchanged).
+    let m38Warnings = [];
+    let m38FileBulk;
+    if (setEntries.length > 0) {
+        const m38 = await preCheckM38FileDispatch({
+            client,
+            boardId,
+            setEntries,
+            setRawCount: rawEntries.length,
+            hasName: parsed.name !== undefined,
+            callShape: 'item_update_bulk',
+            env: ctx.env,
+            noCache: globalFlags.noCache,
+        });
+        // Round-2 P3-1 fix carry-forward: capture pre-check warnings
+        // to thread them into the final envelope. Pre-check resolution
+        // warnings (column_token_collision / stale_cache_refreshed)
+        // survive even though downstream cache hits suppress
+        // re-emission.
+        m38Warnings = m38.warnings;
+        if (m38.kind === 'file_bulk') {
+            // v0.7-M42 D5 carve-out fold. Hold the file_bulk slot for
+            // the items_page-walked dispatch leg below; the items_page
+            // walker still runs (collects target item IDs) + the
+            // confirmation gate still applies + the dispatch loop fans
+            // `executeFileColumnSet` across matched items.
+            m38FileBulk = m38;
+        }
+    }
     const onColumnNotFound = meta.source === 'cache'
         ? async () => {
             const refreshed = await refreshBoardMetadata({
@@ -576,6 +756,13 @@ const runBulk = async (inputs) => {
     // aggregate to `mixed` when metadata was cache-served.
     const emptyEnvelopeSource = meta.source === 'cache' ? 'mixed' : 'live';
     if (matchedItemIds.length === 0) {
+        // Round-2 P3-1 fix: thread M38 pre-check warnings into the
+        // empty-match envelope so a pre-check `stale_cache_refreshed`
+        // / `column_token_collision` survives the no-op short-circuit.
+        const emptyWarnings = dedupeWarnings([
+            ...filterResult.warnings,
+            ...m38Warnings,
+        ]);
         if (globalFlags.dryRun) {
             emitDryRun({
                 ctx,
@@ -583,7 +770,7 @@ const runBulk = async (inputs) => {
                 plannedChanges: [],
                 source: emptyEnvelopeSource,
                 cacheAgeSeconds: meta.cacheAgeSeconds,
-                warnings: filterResult.warnings,
+                warnings: emptyWarnings,
                 apiVersion,
             });
             return;
@@ -596,7 +783,7 @@ const runBulk = async (inputs) => {
             },
             schema: bulkLiveDataSchema,
             programOpts,
-            warnings: filterResult.warnings,
+            warnings: emptyWarnings,
             source: emptyEnvelopeSource,
             cacheAgeSeconds: meta.cacheAgeSeconds,
             apiVersion,
@@ -627,6 +814,40 @@ const runBulk = async (inputs) => {
     // fail-fast invariant. (See step 0 above — moving the parse there
     // means a malformed --set / --set-raw doesn't pay for the metadata
     // load + items_page walk first.)
+    // v0.7-M42 D5 carve-out fold — bulk file `--set` dispatch leg.
+    // When the pre-check returned `kind: 'file_bulk'`, branch into
+    // the per-item multipart fan-out helper here. The branch fires
+    // AFTER the items_page walker + confirmation gate (so an agent
+    // sees the matched-count via `confirmation_required` before
+    // the bulk file dispatch fans out) and BEFORE the JSON
+    // translator path's `resolveAndTranslate` call (which has
+    // nothing to translate when every `--set` is a file column).
+    //
+    // The helper runs single upfront `precheckLocalFile` + per-item
+    // `executeFileColumnSet` (fail-fast vs `--continue-on-error`
+    // per `parsed.continueOnError`; sequential vs parallel per
+    // `parsed.concurrency`) + post-dispatch `invalidateBoard` +
+    // envelope emit (`operation: 'item_update_bulk_file_set'`).
+    if (m38FileBulk !== undefined) {
+        await runItemUpdateBulkFileDispatch({
+            parsed,
+            client,
+            multipart,
+            ctx,
+            programOpts,
+            apiVersion,
+            boardId,
+            matchedItemIds,
+            m38: m38FileBulk,
+            metaSource: meta.source,
+            metaCacheAgeSeconds: meta.cacheAgeSeconds,
+            filterWarnings: filterResult.warnings,
+            retries: globalFlags.retry,
+            isDryRun: globalFlags.dryRun,
+            noCache: globalFlags.noCache,
+        });
+        return;
+    }
     const { dateResolution, peopleResolution, tagResolution, relationResolution } = buildResolutionContexts({ client, ctx, globalFlags });
     // 5) Dry-run path: per-item planChanges. Column resolution is
     //    cached after the first call; per-item state read fires per
@@ -639,26 +860,53 @@ const runBulk = async (inputs) => {
     // the resolver-warning preservation pattern is meant to keep.
     if (globalFlags.dryRun) {
         const allPlanned = [];
-        const aggregatedWarnings = [...filterResult.warnings];
+        // Round-2 P3-1 fix: seed `aggregatedWarnings` with pre-check
+        // warnings so `stale_cache_refreshed` survives even though
+        // downstream per-item planChanges cache-hits suppress
+        // re-emission.
+        const aggregatedWarnings = [
+            ...filterResult.warnings,
+            ...m38Warnings,
+        ];
         const sourceAgg = new SourceAggregator({
             source: meta.source,
             cacheAgeSeconds: meta.cacheAgeSeconds,
         });
         for (const itemId of matchedItemIds) {
-            const result = await planChanges({
-                client,
-                boardId,
-                itemId,
-                setEntries,
-                ...(rawEntries.length === 0 ? {} : { rawEntries }),
-                ...(parsed.name === undefined ? {} : { nameChange: parsed.name }),
-                dateResolution,
-                peopleResolution,
-                tagResolution,
-                relationResolution,
-                env: ctx.env,
-                noCache: globalFlags.noCache,
-            });
+            // v0.7-M42 IMPL: clean bulk file `--set` paths branched into
+            // `runItemUpdateBulkFileDispatch` above (the `m38FileBulk !==
+            // undefined` arm) and returned before reaching this loop, so
+            // this dry-run body only ever sees JSON-shaped paths.
+            // `--set-raw <file-col>=<json>` still rejects normally via
+            // `translateRawColumnValue`'s D3 permanent rejection.
+            let result;
+            try {
+                result = await planChanges({
+                    client,
+                    boardId,
+                    itemId,
+                    setEntries,
+                    ...(rawEntries.length === 0 ? {} : { rawEntries }),
+                    ...(parsed.name === undefined ? {} : { nameChange: parsed.name }),
+                    dateResolution,
+                    peopleResolution,
+                    tagResolution,
+                    relationResolution,
+                    env: ctx.env,
+                    noCache: globalFlags.noCache,
+                });
+            }
+            catch (err) {
+                // Round-3 P3-1 fix: fold M38 pre-check warnings into the
+                // per-item failure envelope so a pre-check
+                // `stale_cache_refreshed` rides into the error's
+                // `details.resolver_warnings` even when the per-item
+                // planChanges throws.
+                if (err instanceof MondayCliError && m38Warnings.length > 0) {
+                    throw mergeResolverWarningsIntoError(err, m38Warnings);
+                }
+                throw err;
+            }
             for (const plan of result.plannedChanges) {
                 allPlanned.push(plan);
             }
@@ -703,25 +951,54 @@ const runBulk = async (inputs) => {
     // is the narrowed subset used by foldResolverWarningsIntoError —
     // the helper's contract is to fold collision / stale_cache_refreshed
     // signals, not generic Warning types.
-    const resolutionResult = await resolveAndTranslate({
-        client,
-        boardId,
-        setEntries,
-        rawEntries,
-        dateResolution,
-        peopleResolution,
-        tagResolution,
-        relationResolution,
-        env: ctx.env,
-        noCache: globalFlags.noCache,
-        initialSource: meta.source,
-        initialCacheAgeSeconds: meta.cacheAgeSeconds,
-    });
-    const collectedWarnings = [
+    // v0.6-M38 D5 file-set rejection already fired at the pre-check
+    // above (step 1.5). resolveAndTranslate processes only non-file
+    // setEntries here.
+    let resolutionResult;
+    try {
+        resolutionResult = await resolveAndTranslate({
+            client,
+            boardId,
+            setEntries,
+            rawEntries,
+            dateResolution,
+            peopleResolution,
+            tagResolution,
+            relationResolution,
+            env: ctx.env,
+            noCache: globalFlags.noCache,
+            initialSource: meta.source,
+            initialCacheAgeSeconds: meta.cacheAgeSeconds,
+        });
+    }
+    catch (err) {
+        // Round-3 P3-1 fix: fold M38 pre-check warnings into the
+        // bulk-live failure envelope's `details.resolver_warnings`.
+        if (err instanceof MondayCliError && m38Warnings.length > 0) {
+            throw mergeResolverWarningsIntoError(err, m38Warnings);
+        }
+        throw err;
+    }
+    // Round-2 P3-1 fix: include M38 pre-check warnings in the live
+    // bulk envelope's aggregated warnings. Pre-check warnings are
+    // deduped against downstream resolveAndTranslate warnings so
+    // `stale_cache_refreshed` surfaces exactly once.
+    const collectedWarnings = dedupeWarnings([
         ...filterResult.warnings,
+        ...m38Warnings,
         ...resolutionResult.warnings,
-    ];
-    const resolverWarnings = [...resolutionResult.warnings];
+    ]);
+    // Round-3 P3-2 fix: include M38 pre-check warnings in
+    // `resolverWarnings`. This is the slot threaded into
+    // `foldAndRemap` for fail-fast bulk errors + partial-success
+    // results — without the pre-check leg, a pre-check
+    // `stale_cache_refreshed` is absent from per-item failure
+    // envelopes (and per-item partial-success records' error
+    // details).
+    const resolverWarnings = dedupeWarnings([
+        ...m38Warnings,
+        ...resolutionResult.warnings,
+    ]);
     const resolvedIds = resolutionResult.resolvedIds;
     // resolveAndTranslate was seeded with meta.source / meta.cacheAge
     // above, so resolutionResult.source is always defined post-helper.
@@ -932,4 +1209,674 @@ const runBulk = async (inputs) => {
         resolvedIds,
     });
 };
+const runItemUpdateSingleFileDispatch = async (inputs) => {
+    const precheck = await precheckLocalFile(inputs.m38.rawValue);
+    if (inputs.isDryRun) {
+        emitDryRun({
+            ctx: inputs.ctx,
+            programOpts: inputs.programOpts,
+            plannedChanges: [
+                {
+                    operation: 'add_file_to_column',
+                    item_id: inputs.itemId,
+                    column_id: inputs.m38.columnId,
+                    file_path: inputs.m38.rawValue,
+                    filename: precheck.filename,
+                    file_size_bytes: precheck.fileSizeBytes,
+                },
+            ],
+            source: 'none',
+            cacheAgeSeconds: null,
+            warnings: inputs.m38.warnings,
+            apiVersion: inputs.apiVersion,
+        });
+        return;
+    }
+    const result = await executeFileColumnSet({
+        client: inputs.client,
+        multipart: inputs.multipart,
+        itemId: inputs.itemId,
+        entry: {
+            columnId: inputs.m38.columnId,
+            columnType: 'file',
+            rawValue: inputs.m38.rawValue,
+            filePath: precheck.filePath,
+            filename: precheck.filename,
+            fileSizeBytes: precheck.fileSizeBytes,
+        },
+        signal: inputs.ctx.signal,
+        retries: inputs.retries,
+    });
+    // §8 single-leg cache invalidation BEFORE emit (mirrors M31).
+    await invalidateBoard(inputs.boardId, inputs.ctx.env);
+    const data = {
+        operation: 'add_file_to_column',
+        item_id: inputs.itemId,
+        column_id: inputs.m38.columnId,
+        filename: precheck.filename,
+        file_size_bytes: precheck.fileSizeBytes,
+        asset: result.asset,
+    };
+    emitMutation({
+        ctx: inputs.ctx,
+        data,
+        schema: fileColumnSetOutputSchema,
+        programOpts: inputs.programOpts,
+        warnings: inputs.m38.warnings.map((w) => ({
+            code: w.code,
+            message: w.message,
+            details: w.details,
+        })),
+        ...inputs.toEmit({
+            data: result.asset,
+            complexity: result.complexity,
+            stats: { attempts: 1, totalBackoffMs: 0 },
+        }),
+        source: 'live',
+        cacheAgeSeconds: null,
+        complexity: result.complexity,
+        resolvedIds: { [inputs.m38.token]: inputs.m38.columnId },
+    });
+};
+// ============================================================
+// v0.7-M42 bulk file `--set` carve-out fold (D5 closure from
+// v0.6-M38). Per-item multipart fan-out over the `--where`-resolved
+// item-id set, reusing v0.4-M31's `executeFileColumnSet` runtime
+// body verbatim under v0.4-M30's `dispatchParallel` /
+// `dispatchSequential` selector for `--concurrency` semantics.
+//
+// **Status: runtime body shipped at v0.7-M42 IMPL.** The pre-flight
+// contract diff (commit `160330b`) shipped the argv + pre-check +
+// items_page + confirmation-gate surface plus the per-item dispatch
+// stub that threw `internal_error` with `details.reason:
+// 'm42_preflight_stub'`; IMPL replaces the stub with the runtime
+// body below. The `'m42_preflight_stub'` literal is RESERVED across
+// the codebase (regression-guarded by an integration test that
+// asserts the literal does not appear in stdout/stderr); a
+// historical `'file_set_on_bulk_unsupported'` literal stays
+// reserved alongside it.
+//
+// **D-list closures (v0.7-plan §3 M42 entry):**
+//
+//   - **D1 — `--concurrency` semantics for file dispatch.** Reuse
+//     v0.4-M30's `dispatchParallel` over a shared
+//     `MultipartTransport`. Each parallel worker constructs its
+//     own `MultipartTransportRequest` per call; the transport
+//     itself is connection-pool-shared per-token. Closes by
+//     inheritance from M30 (concurrency probe pinned at
+//     `scripts/probe/m30-concurrency.report.txt`) + M31 (multipart
+//     wire pinned at `scripts/probe/m31-asset-upload.report.txt`).
+//     No new probe required.
+//
+//   - **D2 — Per-item asset slot in envelope.** Per-item
+//     `data.results[i].asset: { id, name, ... }` echo on success
+//     (mirrors M31's `itemUploadOutputSchema`'s `asset` slot);
+//     per-item failure surfaces as
+//     `data.results[i].error: { code, message }` per M25
+//     partial-success. Aggregate `data.summary.{matched_count,
+//     applied_count, failed_count, board_id, column_id, filename,
+//     file_size_bytes}` extends M25's
+//     `partialSuccessBulkUpdateDataSchema` with file-dispatch slots
+//     so an agent reading the envelope sees which file was
+//     dispatched + where.
+//
+//   - **D3 — Per-item file pre-check timing.** Single upfront
+//     `precheckLocalFile` call BEFORE the per-item dispatch loop —
+//     the bulk shape has ONE file path (the value of the file
+//     `--set`) shared across N matched items. A failed pre-check
+//     surfaces upfront as `usage_error` with `details.reason:
+//     'file_not_readable'` / `'file_empty'` (mirrors M31 single-
+//     item shape) — this is whole-call-abort regardless of
+//     `--continue-on-error`, per cli-design §5.8's "pre-checks
+//     MUST fire BEFORE any wire round-trip" atomicity discipline.
+//     The `--continue-on-error` flag partitions ONLY the wire-
+//     dispatch failures (per-item `add_file_to_column` rejections
+//     from Monday), never the local file pre-check.
+//
+//   - **D4 — ERROR_CODES delta.** Zero. Registry stays at 29.
+//     Per-item dispatch failures route through the existing
+//     `m25-shaped` per-record `error: { code, message }` shape
+//     under `--continue-on-error`, or through the v0.1 fail-fast
+//     decoration (`details.applied_to` + `applied_count` +
+//     `failed_at_item` + `matched_count`) on the default path;
+//     no new top-level code surfaces.
+//
+// **R-class watch-items.**
+//
+//   - R-v0.6-NEW-1 (file pre-check + Blob-construction helper) —
+//     `precheckLocalFile` consumer count goes 3 → 4 at IMPL (M31
+//     item upload + M31 update upload + M38 item set / item update
+//     single + M42 bulk item update). Already-shipped helper
+//     scales cleanly to consumer 4; graduation candidate at the
+//     5th consumer (v0.7-M43 create-time fold likely tips it).
+//   - R-v0.6-NEW-2 (`details.reason` discriminator pattern) — 4
+//     instances at v0.6-M38; M42 IMPL adds zero new reasons (per
+//     D4 zero-delta closure — the existing `'file_not_readable'`
+//     / `'file_empty'` / `'multi_file_set_unsupported'` /
+//     `'mixed_file_and_value_sets'` reasons cover every M42
+//     rejection shape).
+//   - R-NEW-76 (parseArgv-BEFORE-c8) — applied at pre-flight; the
+//     c8-ignore boundary dropped at IMPL (runtime body fully
+//     covered).
+//   - R-NEW-72 (post-fix-up cross-doc grep) — apply at every
+//     Codex IMPL fix-up round that flips a contract surface.
+//
+// **Future lift candidate.** The fail-fast error-decoration block
+// (`if (err.code === 'usage_error') { throw new UsageError(...) } else
+// { throw new ApiError(...) }`) is byte-equivalent across this
+// helper and the JSON-bulk action body (R-NEW-58 2-consumer
+// trigger). Lift candidate fires at the 3rd consumer (M43 create-
+// time fold may add one if its rollback / orphan-warn shape
+// re-uses the same decoration).
+// ============================================================
+/**
+ * Per-item dispatch result for v0.7-M42 bulk file `--set` carve-out
+ * fold. Mirrors the M25 `partialSuccessBulkUpdateResultSchema` shape
+ * with the file-dispatch's `asset` slot replacing the JSON path's
+ * `item` projection:
+ *
+ *   - Success: `{ item_id, ok: true, asset: { id, name, ... } }`
+ *   - Failure: `{ item_id, ok: false, error: { code, message } }`
+ *
+ * Schema landed at the v0.7-M42 pre-flight contract diff
+ * (`160330b`); runtime body shipped at v0.7-M42 IMPL (`22df2fa`)
+ * + R1 fix-up (`968b154`).
+ */
+export const bulkFileSetResultSchema = z.object({
+    item_id: z.string().min(1),
+    ok: z.boolean(),
+    asset: z
+        .object({
+        id: z.string().min(1),
+        name: z.string().min(1),
+    })
+        .loose()
+        .optional(),
+    error: z
+        .object({
+        code: z.string().min(1),
+        message: z.string().min(1),
+    })
+        .optional(),
+});
+/**
+ * Output `data` shape for the v0.7-M42 bulk file `--set` envelope.
+ * Mirrors M25's `partialSuccessBulkUpdateDataSchema` structure —
+ * `operation: 'item_update_bulk_file_set'` literal discriminator
+ * + `summary.{matched_count, applied_count, failed_count,
+ * board_id}` aggregate slots + per-item `results[]` array.
+ *
+ * Invariant: `matched_count === applied_count + failed_count` for
+ * every emitted envelope (mirrors M25's invariant).
+ */
+export const bulkFileSetDataSchema = z.object({
+    operation: z.literal('item_update_bulk_file_set'),
+    summary: z.object({
+        matched_count: z.number().int().nonnegative(),
+        applied_count: z.number().int().nonnegative(),
+        failed_count: z.number().int().nonnegative(),
+        board_id: z.string().min(1),
+        column_id: z.string().min(1),
+        filename: z.string().min(1),
+        file_size_bytes: z.number().int().nonnegative(),
+    }),
+    results: z.array(bulkFileSetResultSchema),
+});
+/**
+ * Bulk file `--set` per-item dispatch helper (v0.7-M42 D5 carve-out
+ * fold).
+ *
+ * **Status: runtime body shipped at v0.7-M42 IMPL.** argv parse,
+ * shape validation, board-metadata load, pre-check (which returned
+ * `kind: 'file_bulk'` for callers reaching this helper), items_page
+ * walk, and the confirmation gate run upstream — this helper takes
+ * the resolved file-column dispatch slot + matched item-IDs and
+ * fans the multipart wire across them under the partial-success vs
+ * fail-fast contract.
+ *
+ * **Execution shape:**
+ *
+ *   1. Single upfront `precheckLocalFile(inputs.m38.rawValue)` —
+ *      one file path shared across all matched items. Failure
+ *      surfaces as `usage_error` (`file_not_readable` /
+ *      `file_empty`) whole-call-abort regardless of
+ *      `--continue-on-error` per D3 + cli-design §5.8 atomicity
+ *      discipline (pre-checks MUST fire BEFORE any wire round-trip).
+ *   2. Dry-run branch — emits the D4-shaped envelope with one
+ *      `add_file_to_column` planned_change per matched item-ID
+ *      (no file bytes loaded; no multipart wire). Unlike M38
+ *      single-item which pins `source: 'none'` (its dry-run is
+ *      pure-local), bulk dry-run carries the upstream legs'
+ *      aggregated `source` (metadata load + items_page walk —
+ *      `mixed` when metadata was cache-served, `live` otherwise);
+ *      reaching this branch already paid for those wire legs.
+ *   3. Live dispatch — two shapes per `parsed.continueOnError`:
+ *      - **Fail-fast (default)** — sequential loop over matched
+ *        items (no `--concurrency` per M30 D2 closure:
+ *        `--concurrency requires --continue-on-error`); first
+ *        per-item failure aborts whole-call with the v0.1-shaped
+ *        `details.applied_to` / `applied_count` / `failed_at_item`
+ *        / `matched_count` decoration so agents see how many
+ *        items applied before the failure.
+ *      - **`--continue-on-error`** — routes through
+ *        {@link dispatchSequential} (concurrency `undefined`/`1`)
+ *        or {@link dispatchParallel} (concurrency `> 1`) over a
+ *        shared {@link MultipartTransport}; per-item failures
+ *        land as `data.results[i].error: {code, message}` records,
+ *        successes carry `data.results[i].asset` via a side-map
+ *        fold keyed by `item_id`. `internal_error` re-throws
+ *        whole-call via the shared dispatchers' escape hatch
+ *        (M14 round-2 F1 precedent) so schema drift surfaces as
+ *        top-level `ok: false` rather than per-record.
+ *   4. Cache invalidation — single `invalidateBoard(boardId, env)`
+ *      after the dispatch loop completes (mirrors M38's single-
+ *      leg invalidate timing; one board covers every matched
+ *      item's mutated `asset` slot).
+ *   5. Envelope emit — `data: BulkFileSetData` with the
+ *      `operation: 'item_update_bulk_file_set'` literal
+ *      discriminator + per-item `results[]` + aggregate
+ *      `summary.{matched_count, applied_count, failed_count,
+ *      board_id, column_id, filename, file_size_bytes}`. Warnings
+ *      threaded as `dedupeWarnings([...filterWarnings,
+ *      ...m38.warnings])` (mirrors the JSON-bulk path); source
+ *      derives from `metaSource` (cache-served metadata + live
+ *      wire calls → `mixed`).
+ */
+export const runItemUpdateBulkFileDispatch = async (inputs) => {
+    // 1) Single upfront pre-check (D3 closure). Whole-call abort
+    //    regardless of `--continue-on-error` per cli-design §5.8 —
+    //    the local file pre-check is shared across N matched items,
+    //    so failure aborts the whole call before any multipart wire
+    //    leg fires. `precheckLocalFile` throws `usage_error` with
+    //    `details.reason: 'file_not_readable'` / `'file_empty'`
+    //    (M31 single-item discriminators reused per D4 zero-delta
+    //    closure).
+    const precheck = await precheckLocalFile(inputs.m38.rawValue);
+    // Combined warnings list threaded into every envelope emit below.
+    // Mirrors the JSON-bulk `dedupeWarnings(filter ∪ m38)` pattern at
+    // the action body; key is `code+message+token` so a pre-check
+    // `stale_cache_refreshed` plus a filter-time `stale_cache_refreshed`
+    // for the SAME token collapse to one entry.
+    const combinedWarnings = dedupeWarnings([
+        ...inputs.filterWarnings,
+        ...inputs.m38.warnings,
+    ]);
+    // Source/cache-age aggregator. Seeded with the metadata leg, then
+    // folds the M38 pre-check leg + a synthetic 'live' leg representing
+    // the items_page walker (always live, fired upstream before this
+    // helper). On dry-run the dispatch leg never fires; on live the
+    // dispatch leg adds another 'live' record (idempotent under
+    // `mergeSource` since 'live' + 'live' = 'live'). Codex IMPL R1
+    // P2-1 fix — pre-fix the helper dropped `inputs.m38.source` +
+    // `inputs.m38.cacheAgeSeconds`, so a cache-served file-column
+    // resolution after a live metadata fetch surfaced `'live'`
+    // instead of `'mixed'`. Mirrors the JSON-bulk path's
+    // SourceAggregator pattern at runBulk's dry-run + live legs.
+    const sourceAgg = new SourceAggregator({
+        source: inputs.metaSource,
+        cacheAgeSeconds: inputs.metaCacheAgeSeconds,
+    });
+    if (inputs.m38.source !== undefined) {
+        sourceAgg.record(inputs.m38.source, inputs.m38.cacheAgeSeconds);
+    }
+    // items_page walker always fires live before reaching the helper
+    // (the empty-match short-circuit is the only path that skips it,
+    // and that path emits the envelope upstream — this helper never
+    // sees matchedItemIds.length === 0). Record one synthetic 'live'
+    // leg so the aggregate reflects the wire round-trip cost the
+    // caller already paid.
+    sourceAgg.record('live', null);
+    // 2) Dry-run branch — D4-shaped envelope. One
+    //    `add_file_to_column` planned_change per matched item-ID;
+    //    no file bytes loaded, no multipart wire round-trip. Unlike
+    //    the M38 single-item dry-run (which pins `source: 'none'`
+    //    because its dry-run is pure-local), bulk dry-run carries
+    //    the aggregated upstream `source` — metadata load + items_page
+    //    walk + M38 pre-check already paid for wire legs to reach
+    //    here.
+    if (inputs.isDryRun) {
+        const plannedChanges = inputs.matchedItemIds.map((itemId) => ({
+            operation: 'add_file_to_column',
+            item_id: itemId,
+            column_id: inputs.m38.columnId,
+            file_path: inputs.m38.rawValue,
+            filename: precheck.filename,
+            file_size_bytes: precheck.fileSizeBytes,
+        }));
+        const dryRunAgg = sourceAgg.result();
+        emitDryRun({
+            ctx: inputs.ctx,
+            programOpts: inputs.programOpts,
+            plannedChanges,
+            source: dryRunAgg.source,
+            cacheAgeSeconds: dryRunAgg.cacheAgeSeconds,
+            warnings: combinedWarnings,
+            apiVersion: inputs.apiVersion,
+        });
+        return;
+    }
+    // 3) Live dispatch. Build the shared `FileColumnSetEntry` once —
+    //    every per-item leg uses the SAME local file (one path × N
+    //    items), so `buildBlobFromPath` (inside `executeFileColumnSet`)
+    //    re-reads the bytes per leg rather than sharing one Blob
+    //    instance. Re-reading per-leg is the simpler shape; a future
+    //    optimisation could memoise the bytes if profiling motivates
+    //    it (~bytes × N reads vs ~bytes × 1 read + held in memory).
+    const entry = {
+        columnId: inputs.m38.columnId,
+        columnType: 'file',
+        rawValue: inputs.m38.rawValue,
+        filePath: precheck.filePath,
+        filename: precheck.filename,
+        fileSizeBytes: precheck.fileSizeBytes,
+    };
+    // Live dispatch is always 'live' — fold one more leg into the
+    // aggregator. Idempotent if metadata + pre-check were also live
+    // ('live' + 'live' = 'live'); promotes 'cache' to 'mixed' when
+    // metadata/pre-check served from cache.
+    sourceAgg.record('live', null);
+    const liveAgg = sourceAgg.result();
+    // resolved_ids slot — pre-check returned the resolved column ID
+    // for the file token; echo it into the envelope's
+    // `meta.resolved_ids` so agents can confirm token-to-ID resolution
+    // (mirrors the M38 single-item envelope at `runItemUpdateSingleFileDispatch`).
+    const resolvedIds = { [inputs.m38.token]: inputs.m38.columnId };
+    // Resolution source for foldAndRemap — defaults to 'live' when
+    // pre-check didn't record one (no resolveColumnWithRefresh leg
+    // fired; the only path that's possible is the no-setEntries
+    // shortcut, which doesn't reach this helper). The remap probe
+    // refreshes board metadata + re-checks the file column's
+    // `archived` flag when a Monday-side `validation_failed`
+    // surfaces against cache-served file-column resolution. Codex
+    // IMPL R1 P1-1 fix.
+    const remapSource = inputs.m38.source ?? 'live';
+    // Discriminator for the dispatch shape: fail-fast (default,
+    // applied to the v0.1 fail-fast bulk path's `applied_to` decoration)
+    // vs `--continue-on-error` (partial-success per-record envelope).
+    // M30 D2 closure pins `--concurrency requires --continue-on-error`,
+    // so fail-fast bulk file dispatch is always sequential N=1.
+    const continueOnError = inputs.parsed.continueOnError === true;
+    if (!continueOnError) {
+        // Fail-fast bulk file dispatch. Sequential loop; first per-item
+        // failure aborts whole-call. Track applied (item_id, asset)
+        // pairs so the failure decoration can echo `applied_to` (matches
+        // the JSON-bulk fail-fast pattern at runBulk's main loop).
+        const appliedAssets = [];
+        for (const itemId of inputs.matchedItemIds) {
+            try {
+                const result = await executeFileColumnSet({
+                    client: inputs.client,
+                    multipart: inputs.multipart,
+                    itemId,
+                    entry,
+                    signal: inputs.ctx.signal,
+                    retries: inputs.retries,
+                });
+                appliedAssets.push({ itemId, asset: result.asset });
+            }
+            catch (err) {
+                if (err instanceof MondayCliError) {
+                    // Codex IMPL R1 P2-2 fix: if any prior item applied
+                    // successfully, the board's asset state already mutated
+                    // wire-side — invalidate the cache BEFORE re-throwing the
+                    // fail-fast error so a follow-up read doesn't serve stale
+                    // metadata. Mirrors the M38 single-item invalidate-on-
+                    // success pattern; the JSON-bulk fail-fast path has the
+                    // same gap (unchanged by this commit — separate lift
+                    // candidate per the future-lift-candidate note in the
+                    // module docstring).
+                    if (appliedAssets.length > 0) {
+                        await invalidateBoard(inputs.boardId, inputs.ctx.env);
+                    }
+                    // Codex IMPL R1 P1-1 fix: apply `foldAndRemap` BEFORE
+                    // building the decoration so per-item failures inherit
+                    // the SAME `validation_failed` → `column_archived`
+                    // stale-cache remap the JSON-bulk fail-fast path applies
+                    // (cli-design §6.5 stable-code rule). Without this, an
+                    // archived file column surfaces `validation_failed` on
+                    // file-bulk dispatch but `column_archived` on JSON-bulk
+                    // dispatch — agents keying on the stable code see
+                    // inconsistent outcomes for the same root cause.
+                    const remapped = await foldAndRemap({
+                        err,
+                        warnings: inputs.m38.warnings,
+                        client: inputs.client,
+                        boardId: inputs.boardId,
+                        columnIds: [inputs.m38.columnId],
+                        env: inputs.ctx.env,
+                        noCache: inputs.noCache,
+                        resolutionSource: remapSource,
+                    });
+                    // Same decoration shape as the JSON-bulk fail-fast path
+                    // (lines ~1334-1361 above). Preserves the existing error
+                    // class' fields and grafts `applied_count` / `applied_to`
+                    // / `failed_at_item` / `matched_count` onto `details`.
+                    const existing = remapped.details ?? {};
+                    const decoration = {
+                        ...existing,
+                        applied_count: appliedAssets.length,
+                        applied_to: appliedAssets.map((a) => a.itemId),
+                        failed_at_item: itemId,
+                        matched_count: inputs.matchedItemIds.length,
+                    };
+                    if (remapped.code === 'usage_error') {
+                        throw new UsageError(remapped.message, {
+                            ...(remapped.cause === undefined
+                                ? {}
+                                : { cause: remapped.cause }),
+                            details: decoration,
+                        });
+                    }
+                    throw new ApiError(remapped.code, remapped.message, {
+                        ...(remapped.cause === undefined
+                            ? {}
+                            : { cause: remapped.cause }),
+                        ...(remapped.httpStatus === undefined
+                            ? {}
+                            : { httpStatus: remapped.httpStatus }),
+                        ...(remapped.mondayCode === undefined
+                            ? {}
+                            : { mondayCode: remapped.mondayCode }),
+                        ...(remapped.requestId === undefined
+                            ? {}
+                            : { requestId: remapped.requestId }),
+                        retryable: remapped.retryable,
+                        ...(remapped.retryAfterSeconds === undefined
+                            ? {}
+                            : { retryAfterSeconds: remapped.retryAfterSeconds }),
+                        details: decoration,
+                    });
+                }
+                // Non-CliError programmer bug — re-throw to the runner's
+                // catch-all (surfaces as `internal_error` whole-call;
+                // mirrors the JSON-bulk fail-fast path). The partial-
+                // success invalidate above doesn't fire for this branch
+                // because non-CliError throws indicate broken contract,
+                // not partial-mutation state worth preserving.
+                throw err;
+            }
+        }
+        // Every item applied — single board-cache invalidate before emit
+        // (mirrors M38 single-leg invalidate timing).
+        await invalidateBoard(inputs.boardId, inputs.ctx.env);
+        const results = appliedAssets.map(({ itemId, asset }) => ({
+            item_id: itemId,
+            ok: true,
+            asset,
+        }));
+        const data = {
+            operation: 'item_update_bulk_file_set',
+            summary: {
+                matched_count: inputs.matchedItemIds.length,
+                applied_count: appliedAssets.length,
+                failed_count: 0,
+                board_id: inputs.boardId,
+                column_id: inputs.m38.columnId,
+                filename: precheck.filename,
+                file_size_bytes: precheck.fileSizeBytes,
+            },
+            results,
+        };
+        emitMutation({
+            ctx: inputs.ctx,
+            data,
+            schema: bulkFileSetDataSchema,
+            programOpts: inputs.programOpts,
+            warnings: combinedWarnings,
+            source: liveAgg.source,
+            cacheAgeSeconds: liveAgg.cacheAgeSeconds,
+            apiVersion: inputs.apiVersion,
+            resolvedIds,
+        });
+        return;
+    }
+    // `--continue-on-error` path. Per-item failures land as per-record
+    // `error: {code, message}` slots; the envelope is `ok: true`
+    // regardless of how many items failed (universal partial-success
+    // rule per cli-design §6.4). `internal_error` re-throws whole-call
+    // via the shared dispatcher's escape hatch — schema drift in the
+    // multipart response surfaces as top-level `ok: false`, not
+    // papered over as a per-record slot.
+    const assetById = new Map();
+    const perTargetDispatch = async ({ targetId, }) => {
+        try {
+            const result = await executeFileColumnSet({
+                client: inputs.client,
+                multipart: inputs.multipart,
+                itemId: targetId,
+                entry,
+                signal: inputs.ctx.signal,
+                retries: inputs.retries,
+            });
+            assetById.set(targetId, result.asset);
+        }
+        catch (err) {
+            if (err instanceof MondayCliError) {
+                // Codex IMPL R1 P1-1 fix: apply `foldAndRemap` BEFORE
+                // re-throwing into the shared dispatcher so per-record
+                // `error.code` carries the SAME `column_archived` stable
+                // code the JSON-bulk partial-success path emits. Mirrors
+                // `runPartialSuccessBulkUpdate`'s perTargetDispatch
+                // closure (src/api/partial-success-bulk.ts:431-475).
+                // `foldAndRemap` NEVER converts a non-`internal_error`
+                // into `internal_error`, so the dispatcher's
+                // `internal_error` re-throw escape hatch (M14 round-2 F1)
+                // stays intact: schema drift still surfaces as top-level
+                // `ok: false` rather than papered over as a per-record
+                // slot.
+                const remapped = await foldAndRemap({
+                    err,
+                    warnings: inputs.m38.warnings,
+                    client: inputs.client,
+                    boardId: inputs.boardId,
+                    columnIds: [inputs.m38.columnId],
+                    env: inputs.ctx.env,
+                    noCache: inputs.noCache,
+                    resolutionSource: remapSource,
+                });
+                throw remapped;
+            }
+            // Non-CliError — programmer bug. Re-throw through
+            // dispatchSequential / dispatchParallel's non-CliError
+            // branch so the runner's catch-all surfaces as
+            // internal_error (whole-call, not per-record).
+            throw err;
+        }
+    };
+    // Routing — `--concurrency > 1` routes through dispatchParallel
+    // (bounded async-pool); absent / `=== 1` routes through
+    // dispatchSequential. Both dispatchers thread the optional
+    // `signal` so SIGINT-aware callers see consistent cooperative-
+    // abort semantics (R-NEW-28 axis 6 — identical between routes).
+    let dispatchResults;
+    if (inputs.parsed.concurrency !== undefined &&
+        inputs.parsed.concurrency > 1) {
+        dispatchResults = await dispatchParallel(inputs.matchedItemIds, 'item_id', perTargetDispatch, inputs.parsed.concurrency, inputs.ctx.signal);
+    }
+    else {
+        dispatchResults = await dispatchSequential(inputs.matchedItemIds, 'item_id', perTargetDispatch, inputs.ctx.signal);
+    }
+    // Single post-dispatch invalidate. Fires even when every per-item
+    // dispatch failed (failed_count === matched_count) — wire calls
+    // still fired against Monday, so the metadata cache's view of the
+    // file column's content count may be stale even if the asset
+    // didn't land. Cheap to always fire; expensive if missed.
+    await invalidateBoard(inputs.boardId, inputs.ctx.env);
+    // Fold dispatcher results + side-map assets into the
+    // BulkFileSetResult[] shape. Mirrors `foldPartialSuccessBulkResult`
+    // (`src/api/partial-success-bulk.ts`) but with the file-dispatch's
+    // `asset` slot replacing the JSON path's `item` projection.
+    const results = dispatchResults.map((row) => {
+        const itemIdSlot = row.item_id;
+        /* c8 ignore next 8 — dispatcher contract: every result row
+           carries the id-field slot (populated by the dispatch helper);
+           this guard catches a contract violation that would surface as
+           a programmer bug, not a Monday-side failure. */
+        if (typeof itemIdSlot !== 'string' || itemIdSlot.length === 0) {
+            throw new ApiError('internal_error', 'bulk file dispatch result row is missing the `item_id` field — dispatcher contract violation.', { details: { record_keys: Object.keys(row) } });
+        }
+        if (row.ok) {
+            const asset = assetById.get(itemIdSlot);
+            /* c8 ignore next 8 — side-map invariant: every successful
+               per-target dispatch records the asset; this guard catches a
+               wrapper-layer miss (programmer bug). */
+            if (asset === undefined) {
+                throw new ApiError('internal_error', `bulk file dispatch result row for item_id ${itemIdSlot} reported ok: true but no Asset was captured — wrapper-layer side-map miss.`, { details: { item_id: itemIdSlot } });
+            }
+            return { item_id: itemIdSlot, ok: true, asset };
+        }
+        /* c8 ignore next 8 — dispatcher contract: every `ok: false` row
+           carries the `error` slot (populated by the shared dispatcher's
+           per-target error decoration). */
+        if (row.error === undefined) {
+            throw new ApiError('internal_error', `bulk file dispatch result row for item_id ${itemIdSlot} reported ok: false but no error payload was captured — dispatcher contract violation.`, { details: { item_id: itemIdSlot } });
+        }
+        return {
+            item_id: itemIdSlot,
+            ok: false,
+            error: { code: row.error.code, message: row.error.message },
+        };
+    });
+    const appliedCount = results.filter((r) => r.ok).length;
+    const failedCount = results.filter((r) => !r.ok).length;
+    /* c8 ignore next 11 — invariant: every matched item produces
+       exactly one result row (success or failure) under both
+       dispatchers; mismatch would indicate a programmer bug in the
+       dispatcher or the fold. Mirrors `buildPartialSuccessBulkSummary`'s
+       defensive check. */
+    if (appliedCount + failedCount !== inputs.matchedItemIds.length) {
+        throw new ApiError('internal_error', `bulk file dispatch summary invariant violated — matched_count (${String(inputs.matchedItemIds.length)}) !== applied_count (${String(appliedCount)}) + failed_count (${String(failedCount)}).`, {
+            details: {
+                matched_count: inputs.matchedItemIds.length,
+                applied_count: appliedCount,
+                failed_count: failedCount,
+                board_id: inputs.boardId,
+            },
+        });
+    }
+    const data = {
+        operation: 'item_update_bulk_file_set',
+        summary: {
+            matched_count: inputs.matchedItemIds.length,
+            applied_count: appliedCount,
+            failed_count: failedCount,
+            board_id: inputs.boardId,
+            column_id: inputs.m38.columnId,
+            filename: precheck.filename,
+            file_size_bytes: precheck.fileSizeBytes,
+        },
+        results,
+    };
+    emitMutation({
+        ctx: inputs.ctx,
+        data,
+        schema: bulkFileSetDataSchema,
+        programOpts: inputs.programOpts,
+        warnings: combinedWarnings,
+        source: liveAgg.source,
+        cacheAgeSeconds: liveAgg.cacheAgeSeconds,
+        apiVersion: inputs.apiVersion,
+        resolvedIds,
+    });
+};
 //# sourceMappingURL=update.js.map