monday-cli 0.7.1 → 0.8.0

package/dist/api/file-column-set.js

@@ -36,12 +36,25 @@
  *   2. The atomicity contract differs — the 13 existing types
  *      bundle atomically via `change_multiple_column_values` when
  *      ≥2 columns target the same item. File-column writes are
- *      single-column-per-call only on Monday's wire; mixing a
- *      file-column `--set` with any value `--set` / `--set-raw` /
- *      `--name` in the same call would force a multi-leg dispatch
- *      that breaks the existing atomicity guarantee. M38 enforces
- *      single-file-only via the mutex rules below (D2 closure) —
- *      the existing atomicity contract stays intact.
+ *      single-column-per-wire-call only on Monday's wire (each
+ *      `add_file_to_column` round-trip targets one file column);
+ *      mixing a file-column `--set` with any value `--set` /
+ *      `--set-raw` / `--name` in the same call would force a
+ *      multi-leg dispatch across the multipart + JSON wire
+ *      surfaces that breaks the existing atomicity guarantee
+ *      (M38 enforces the mixed-rule mutex below — D2 closure;
+ *      universal on non-create callShapes, SUPPRESSED on
+ *      `'item_create'` per v0.7-M43 D6 asymmetry). Multi-file
+ *      `--set` CARVED OUT at v0.8-M46 (D2 fold): the CLI now
+ *      routes multi-leg fan-out for the 3 reachable callShapes
+ *      (`'item_update_single'` / `'item_update_bulk'` /
+ *      `'item_create'`), preserving the single-column-per-wire-
+ *      call invariant by firing N sequential
+ *      `add_file_to_column` calls per item. The existing
+ *      atomicity contract on the JSON `column_values` bundle
+ *      stays intact; the multi-file dispatch's atomicity
+ *      envelope (partial-failure shape per D2 closure) is
+ *      separately decorated.
  *   3. The translator's input contract is "value-string-to-JSON-
  *      payload" — file columns take a file path, not a value
  *      string. Path validation + `fs.stat` + `fs.access(R_OK)` +
@@ -82,20 +95,36 @@
  * after metadata loads). When any resolved column has `type ===
  * 'file'`:
  *
- *   - Exactly ONE file `--set` entry allowed per call (single-
- *     file scope; multi-file dispatch defers to v0.7.x — Monday's
- *     `add_file_to_column` is single-column per call on the wire
- *     regardless of how many items the dispatch fans out across,
- *     so this rule is universal).
+ *   - Multi-file `--set` per call — **CARVED OUT at v0.8-M46**
+ *     (D2 fold). At v0.6-M38 + v0.7 this rejected universally
+ *     with `'multi_file_set_unsupported'`; v0.8-M46 lifts the
+ *     CLI mutex for the 3 reachable callShapes
+ *     (`'item_update_single'` / `'item_update_bulk'` /
+ *     `'item_create'`) and routes through new `'file_multi'` /
+ *     `'file_bulk_multi'` / `'file_create_multi'` enforcement
+ *     kinds for the action body's per-item multi-leg fan-out
+ *     (sequential within an item × parallel across items for
+ *     bulk). Monday wire stays single-column-per-wire-call
+ *     (each `add_file_to_column` round-trip targets one file
+ *     column); M46 fans N CLI legs per item rather than
+ *     bundling them on the wire. The throw remains for the
+ *     `'item_set'` callShape as a defensive type-system
+ *     ceiling — `monday item set <iid> <col>=<value>` accepts
+ *     exactly one positional and is argv-incapable of
+ *     expressing 2+ file `--set` entries; the throw is
+ *     unreachable from production argv but kept as defense-in-
+ *     depth.
  *   - NO other value `--set` / `--set-raw` / `--name` flags
  *     allowed (mixing would force non-atomic multi-leg dispatch
- *     across the multipart + JSON wire surfaces).
+ *     across the multipart + JSON wire surfaces — universal on
+ *     `'item_set'` / `'item_update_single'` / `'item_update_bulk'`,
+ *     SUPPRESSED on `'item_create'` per v0.7-M43 D6 asymmetry).
  *   - Bulk `item update --where ... --set <file-col>=<path>` —
  *     **CARVED OUT at v0.7-M42** (D5 fold). At v0.6-M38 this was
  *     REJECTED with `'file_set_on_bulk_unsupported'`; v0.7-M42's
  *     pre-flight contract diff returns
  *     `{ kind: 'file_bulk', columnId, rawValue }` from
- *     {@link enforceSingleFileColumnSet} on the clean dispatch
+ *     {@link routeFileColumnDispatch} on the clean dispatch
  *     path so the action body can branch into the per-item
  *     multipart fan-out. Multi-file / mixed mutex rules STILL
  *     apply on bulk (those are universal).
@@ -104,7 +133,7 @@
  *     `'file_set_on_create_unsupported'`; v0.7-M43's pre-flight
  *     contract diff returns
  *     `{ kind: 'file_create', columnId, rawValue }` from
- *     {@link enforceSingleFileColumnSet} on the clean dispatch
+ *     {@link routeFileColumnDispatch} on the clean dispatch
  *     path so the action body can branch into the two-leg
  *     dispatch (`create_item` then `add_file_to_column`).
  *     Multi-file mutex rule STILL applies on create (universal).
@@ -122,9 +151,20 @@
  *   - `'mixed_file_and_value_sets'` — file `--set` + any value
  *     `--set` / `--set-raw` / `--name` in same call. Applies on
  *     single-item AND bulk call shapes (universal mutex rule).
- *   - `'multi_file_set_unsupported'` — 2+ file `--set` entries
- *     in same call. Applies on single-item AND bulk call shapes
- *     (universal mutex rule).
+ *   - `'multi_file_set_unsupported'` — **NO LONGER SURFACES**
+ *     from `'item_update_single'` / `'item_update_bulk'` /
+ *     `'item_create'` callShapes at v0.8-M46 onwards (D2 carve-out
+ *     fold; multi-file dispatch now routes through new `file_multi`
+ *     / `file_bulk_multi` / `file_create_multi` enforcement kinds
+ *     for the action body's per-item multi-leg fan-out). The
+ *     discriminator literal stays RESERVED across the codebase
+ *     (do not reuse for a different rejection reason; mirrors
+ *     M42 / M43 reserved-literal discipline). The throw remains
+ *     for the `'item_set'` callShape as a defensive type-system
+ *     ceiling — the single-positional `monday item set <iid>
+ *     <col>=<value>` shape is argv-incapable of expressing 2+
+ *     file `--set` entries, so this rejection is argv-unreachable
+ *     in practice; kept as defense-in-depth.
  *   - `'file_set_on_bulk_unsupported'` — **NO LONGER SURFACES**
  *     at v0.7-M42 onwards. Historical reference only; the
  *     discriminator literal stays reserved across the codebase
@@ -146,13 +186,33 @@
  * rejection see the full set of working alternatives rather
  * than just the M38 single-item form.
  *
- * **D7 closure — `<path>='-'` stdin support OUT OF SCOPE.**
- * Mirrors M31 `monday item upload`'s rejection rationale — no
- * clean `--filename` companion shape pinned for `--set
- * <file-col>=-` syntax (stdin reads byte-anonymously; the
- * filename is the load-bearing handle for Monday's wire
- * `Asset.name` slot). Carry-forward candidate for v0.7.x once a
- * `--filename` companion shape is pinned.
+ * **D7 closure — `<path>='-'` stdin support CARVED OUT at
+ * v0.8-M47.** Deferred from v0.6-M38 (no `--filename` companion
+ * shape pinned then); v0.8-M47 pins the OPTIONAL `--filename
+ * <name>` companion (default `"blob"`; Monday accepts any non-empty
+ * `Asset.name` and `500`s only an empty one — probe-pinned) and
+ * accepts a bare `-` file `--set` value as a stdin source. Because
+ * stdin is a single non-replayable stream, the carve-out is scoped
+ * to single-file, single-target dispatch: exactly one
+ * `<file-col>=-` per call, as the SOLE file `--set` entry, on
+ * `item set` / single-item `item update` / `item create`.
+ * {@link routeFileColumnDispatch}'s stdin scope gate (mutex
+ * priority 0) enforces it — `'multiple_stdin_file_sets'` /
+ * `'stdin_file_set_not_sole_file'` / `'stdin_file_set_on_bulk_
+ * unsupported'` reject with `usage_error` (literals reserved). A
+ * clean stdin source routes through the same single-file
+ * `kind: 'file'` / `'file_create'` as a path source; the action
+ * body sources the Blob from `readStdinFileSource`
+ * (`src/utils/file-source.ts`) instead of {@link buildBlobFromPath},
+ * then dispatches it through M31's `addFileToColumn` fetcher directly
+ * (the path leg builds its Blob inside {@link executeFileColumnSet};
+ * the stdin Blob is already in hand). Live read + dispatch shipped at
+ * the v0.8-M47 IMPL alongside the size-less dry-run echo (D4 — a
+ * stream can't be `fs.stat`'d, so the echo omits `file_size_bytes`);
+ * an empty stdin payload rejects `usage_error` with
+ * `details.reason: 'stdin_file_empty'` before any wire activity. The
+ * verb-shaped `monday item upload` stays path-only (no stdin) —
+ * M47 carves out only the friendly `--set` path.
  *
  * **No new ERROR_CODE (D8 closure; registry stays at 29).** All
  * M38-specific rejections route through existing `usage_error`
@@ -169,8 +229,8 @@
  * canonical cross-link.
  */
 import { z } from 'zod';
-import { ApiError } from '../utils/errors.js';
-import { buildBlobFromPath } from '../utils/file-source.js';
+import { ApiError, MondayCliError } from '../utils/errors.js';
+import { buildBlobFromPath, isStdinFileSetSource } from '../utils/file-source.js';
 import { addFileToColumn, assetSchema } from './assets.js';
 import { resolveColumnWithRefresh } from './columns.js';
 import { foldResolverWarningsIntoError } from './resolver-error-fold.js';
@@ -199,6 +259,42 @@ export const fileColumnSetOutputSchema = z
     asset: assetSchema,
 })
     .strict();
+/**
+ * Output envelope shape for the v0.8-M46 multi-file `--set` dispatch
+ * leg on single-item `monday item update <iid> --set f1=p1 --set
+ * f2=p2 ...`. Discriminate from M38's single-file envelope via the
+ * new `operation: 'add_files_to_columns'` literal (plural) — agents
+ * branch on `data.operation` to handle single vs multi shapes
+ * uniformly.
+ *
+ * Per-file slot mirrors M31's `Asset` shape verbatim wrapped under
+ * a `column_id` + `filename` + `file_size_bytes` per-entry context.
+ * The `applied_file_columns` slot echoes the file columns that
+ * landed on success (length N; always present on multi-file success
+ * envelopes).
+ *
+ * **Status: schema landed at v0.8-M46 pre-flight contract diff;
+ * runtime emit shipped at v0.8-M46 IMPL.**
+ * `runItemUpdateSingleFileMultiDispatch` (commands/item/update.ts)
+ * emits against this schema on the single-item multi-file path.
+ */
+export const fileColumnSetMultiOutputSchema = z
+    .object({
+    operation: z.literal('add_files_to_columns'),
+    item_id: z.string().min(1),
+    assets: z
+        .array(z
+        .object({
+        column_id: z.string().min(1),
+        filename: z.string().min(1),
+        file_size_bytes: z.number().int().nonnegative(),
+        asset: assetSchema,
+    })
+        .strict())
+        .min(2),
+    applied_file_columns: z.array(z.string().min(1)).min(2),
+})
+    .strict();
 /**
  * Reads the local file at `inputs.entry.filePath`, constructs a Blob
  * via {@link buildBlobFromPath} (with `Content-Type` sniffed from the
@@ -219,7 +315,7 @@ export const fileColumnSetOutputSchema = z
  *   1. Parsing argv + collecting `--set` / `--set-raw` / `--name`
  *      entries.
  *   2. Resolving columns via `resolveColumnWithRefresh`.
- *   3. Calling {@link enforceSingleFileColumnSet} to detect the
+ *   3. Calling {@link routeFileColumnDispatch} to detect the
  *      file-column dispatch leg + enforce the mutex rules.
  *   4. Running {@link precheckLocalFile} from
  *      `src/utils/file-source.ts` on the agent-supplied path to
@@ -254,6 +350,79 @@ export const executeFileColumnSet = async (inputs) => {
         complexity: result.complexity,
     };
 };
+/**
+ * Sequential multi-leg `add_file_to_column` fan-out shared by the
+ * three v0.8-M46 multi-file callShape helpers
+ * (`runItemUpdateSingleFileMultiDispatch` /
+ * `runItemUpdateBulkFileMultiDispatch` per-item worker /
+ * `runItemCreateFileMultiDispatch`). R-v0.8-NEW-1 lift — the inner
+ * loop + partial-failure accumulator is byte-identical across all 3
+ * sites; only the envelope decoration diverges (kept in the caller).
+ *
+ * **Sequential within an item (D1 closure).** Legs fire in
+ * `inputs.entries` order so `appliedColumns` echoes the file columns
+ * that landed before a failure in dispatch order. The bulk path
+ * achieves cross-item parallelism by invoking this helper inside each
+ * per-item `dispatchParallel` worker — parallel ACROSS items ×
+ * sequential WITHIN each item.
+ *
+ * **Failure handling.** A `MondayCliError` from any leg stops the
+ * loop and returns the accumulator with `failure` populated (the
+ * caller decorates + optionally remaps). A non-`MondayCliError`
+ * (programmer bug in the wire layer) re-throws to the runner's
+ * catch-all so it surfaces as a whole-call `internal_error` rather
+ * than masquerading as a recoverable partial failure — mirrors the
+ * non-CliError re-throw arms in M42's bulk + M43's create-time
+ * single-file dispatch helpers.
+ */
+export const dispatchFileLegsSequentially = async (inputs) => {
+    const assets = [];
+    const appliedColumns = [];
+    let lastComplexity = null;
+    for (const entry of inputs.entries) {
+        try {
+            const result = await executeFileColumnSet({
+                client: inputs.client,
+                multipart: inputs.multipart,
+                itemId: inputs.itemId,
+                entry: {
+                    columnId: entry.columnId,
+                    columnType: 'file',
+                    rawValue: entry.rawValue,
+                    filePath: entry.filePath,
+                    filename: entry.filename,
+                    fileSizeBytes: entry.fileSizeBytes,
+                },
+                signal: inputs.signal,
+                retries: inputs.retries,
+            });
+            assets.push({
+                column_id: entry.columnId,
+                filename: entry.filename,
+                file_size_bytes: entry.fileSizeBytes,
+                asset: result.asset,
+            });
+            appliedColumns.push(entry.columnId);
+            lastComplexity = result.complexity;
+        }
+        catch (err) {
+            if (err instanceof MondayCliError) {
+                return {
+                    appliedColumns,
+                    assets,
+                    lastComplexity,
+                    failure: { failedColumn: entry.columnId, cause: err },
+                };
+            }
+            // Non-CliError programmer bug — re-throw to the runner's
+            // catch-all (whole-call `internal_error`). Routing it through
+            // a partial-failure envelope would falsely promise a recovery
+            // handle for a broken contract.
+            throw err;
+        }
+    }
+    return { appliedColumns, assets, lastComplexity };
+};
 /**
  * Iterates `inputs.setEntries`, identifies entries with
  * `columnType === 'file'`, applies the mutex rules per D2 / D5 / D6
@@ -262,19 +431,39 @@ export const executeFileColumnSet = async (inputs) => {
  * throws `ApiError('usage_error', ...)` on a mutex violation.
  *
  * Mutex priority (ratified at M38 pre-flight; updated at v0.7-M42
- * + v0.7-M43 pre-flights to fold the D5 bulk + D6 create carve-outs):
+ * + v0.7-M43 pre-flights to fold the D5 bulk + D6 create carve-outs;
+ * updated at v0.8-M46 pre-flight to fold the D2 multi-file carve-out;
+ * updated at v0.8-M47 pre-flight to add the stdin scope gate):
  *
- *   1. **callShape gate — NONE remaining post-v0.7-M43** — both
- *      `'item_update_bulk'` (D5 fold at v0.7-M42) and `'item_create'`
- *      (D6 fold at v0.7-M43) short-circuit-throws have been removed.
- *      Every callShape falls through to the universal multi-file
- *      gate + a callShape-aware mixed gate, then returns a per-
- *      callShape `kind` on the clean path.
- *   2. **multi-file leg** — 2+ file `--set` entries (any callShape)
- *      surface `'multi_file_set_unsupported'`. Universal rule:
- *      Monday's `add_file_to_column` is single-column per call on
- *      the wire regardless of fan-out shape.
- *   3. **mixed leg** — 1 file `--set` + any value `--set` /
+ *   0. **stdin scope gate (v0.8-M47 D7 fold).** When ≥1 file `--set`
+ *      value is the bare `-` stdin sentinel, enforce stdin's single-
+ *      file / single-target scope: `'multiple_stdin_file_sets'` (2+
+ *      `=-`), `'stdin_file_set_not_sole_file'` (stdin + another file
+ *      `--set`), `'stdin_file_set_on_bulk_unsupported'` (`=-` on the
+ *      `'item_update_bulk'` callShape). All `usage_error`; literals
+ *      reserved. A clean stdin source (exactly one `=-`, sole file,
+ *      single-target) falls through to the clean single-file leg and
+ *      returns `kind: 'file'` / `'file_create'` — identical routing to
+ *      a path source; the action body sources the Blob from stdin. The
+ *      mixed + duplicate gates below still apply to a stdin entry.
+ *   1. **callShape gate — ONLY `'item_set'` defensive throw remains**
+ *      post-v0.8-M46. The v0.6-M38 `'item_update_bulk'` (D5 fold at
+ *      v0.7-M42) and `'item_create'` (D6 fold at v0.7-M43) short-
+ *      circuit-throws have been removed; the v0.6-M38 universal
+ *      multi-file throw FOLDED at v0.8-M46 (D2) for the 3 reachable
+ *      callShapes. The `'item_set'` callShape's multi-file throw
+ *      stays as defensive type-system ceiling — the single-
+ *      positional `monday item set <iid> <col>=<value>` verb is
+ *      argv-incapable of expressing 2+ file `--set` entries, so
+ *      this branch is argv-unreachable in practice; kept as
+ *      defense-in-depth.
+ *   2. **multi-file leg (`'item_set'` only post-fold)** — 2+ file
+ *      `--set` entries on `'item_set'` callShape surface
+ *      `'multi_file_set_unsupported'` (argv-unreachable defensive).
+ *      The other 3 reachable callShapes (`'item_update_single'` /
+ *      `'item_update_bulk'` / `'item_create'`) fall through to the
+ *      mixed gate + clean leg for the multi-file dispatch routing.
+ *   3. **mixed leg** — 1+ file `--set` + any value `--set` /
  *      `--set-raw` / `--name` surfaces `'mixed_file_and_value_sets'`
  *      on `'item_set'` / `'item_update_single'` / `'item_update_bulk'`.
  *      Universal rule on those callShapes: mixing forces non-atomic
@@ -283,29 +472,106 @@ export const executeFileColumnSet = async (inputs) => {
  *      asymmetry — `create_item` natively bundles non-file
  *      `column_values` atomically into leg-1, and `--name` is
  *      required on create.
- *   4. **clean leg** — 1 file `--set`, no mutex violation:
- *      - `'item_update_single'` / `'item_set'` → return
- *        `{ kind: 'file', columnId, rawValue }` for downstream
- *        {@link precheckLocalFile} + {@link executeFileColumnSet}
- *        (M38 path; unchanged).
- *      - `'item_update_bulk'` → return `{ kind: 'file_bulk',
- *        columnId, rawValue }` for the action body's per-item
- *        multipart fan-out (v0.7-M42 D5 carve-out fold).
- *      - `'item_create'` → return `{ kind: 'file_create', columnId,
- *        rawValue }` for the action body's two-leg `create_item`
- *        then `add_file_to_column` helper (v0.7-M43 D6 carve-out
- *        fold).
+ *   4. **clean leg** — ≥1 file `--set`, no mutex violation. Branches
+ *      on N (single vs multi) then callShape:
+ *      - N=1 (single-file path):
+ *        - `'item_update_single'` / `'item_set'` → `{ kind: 'file',
+ *          columnId, rawValue }` (M38 path; unchanged).
+ *        - `'item_update_bulk'` → `{ kind: 'file_bulk', ... }`
+ *          (v0.7-M42 D5 carve-out fold).
+ *        - `'item_create'` → `{ kind: 'file_create', ... }`
+ *          (v0.7-M43 D6 carve-out fold).
+ *      - N>1 (multi-file path — v0.8-M46 D2 carve-out fold):
+ *        - `'item_update_single'` → `{ kind: 'file_multi', entries }`
+ *          for the single-item multi-leg fan-out helper.
+ *        - `'item_update_bulk'` → `{ kind: 'file_bulk_multi',
+ *          entries }` for the bulk per-item multi-leg fan-out.
+ *        - `'item_create'` → `{ kind: 'file_create_multi', entries }`
+ *          for the create-time two-leg-group multi-file helper.
  *
  * The function is sync + pure. No I/O. Path validation lives at a
  * SEPARATE step (`precheckLocalFile` from `src/utils/file-source.ts`)
- * that the caller runs AFTER this function returns a `kind: 'file'`
+ * that the caller runs AFTER this function returns a `kind: 'file*'`
  * result.
  */
-export const enforceSingleFileColumnSet = (inputs) => {
+export const routeFileColumnDispatch = (inputs) => {
     const fileSetEntries = inputs.setEntries.filter((e) => e.columnType === 'file');
     if (fileSetEntries.length === 0) {
         return { kind: 'json' };
     }
+    // v0.8-M47 stdin file `--set` scope gate (D7 fold). A file `--set`
+    // value of the bare `-` sentinel sources the file body from stdin.
+    // stdin is a single non-replayable stream, so the contract scopes it
+    // to single-file, single-target dispatch (D-list closures at
+    // v0.8-plan §3 M47): exactly one `<file-col>=-` per call, as the
+    // SOLE file entry, on a single-target callShape. The three
+    // violations reject with `usage_error` + a reserved `details.reason`
+    // discriminator (no new ERROR_CODE — registry stays 29). A clean
+    // stdin source falls through to the single-file clean leg below and
+    // returns `kind: 'file'` (single-item update) / `'file_create'`
+    // (create) just like a path source — the rawValue carries the `-`
+    // sentinel and the action body's dispatch helper sources from stdin
+    // (via `readStdinFileSource`) instead of `precheckLocalFile`. The
+    // mixed-rule + duplicate-column checks below still apply to a stdin
+    // entry (e.g. `--set f=- --set status=Done` rejects `mixed_file_and_
+    // value_sets`); stdin only changes the file SOURCE, not the mutex
+    // surface around it.
+    const stdinFileEntries = fileSetEntries.filter((e) => isStdinFileSetSource(e.rawValue));
+    if (stdinFileEntries.length > 0) {
+        const firstStdin = stdinFileEntries[0];
+        /* c8 ignore next 6 — defensive: length > 0 guarantees [0] is
+           defined; the guard exists for `noUncheckedIndexedAccess`
+           narrowing (mirrors the `fe === undefined` guards below). */
+        if (firstStdin === undefined) {
+            throw new ApiError('internal_error', 'routeFileColumnDispatch: stdin entry narrowing failed');
+        }
+        if (stdinFileEntries.length > 1) {
+            throw new ApiError('usage_error', `Only one \`--set <file-col>=-\` stdin source is allowed per call ` +
+                `(stdin is a single non-replayable stream — it can't be split ` +
+                `across multiple file columns). Pass at most one \`<file-col>=-\` ` +
+                `and use local file paths for the rest.`, {
+                details: {
+                    reason: 'multiple_stdin_file_sets',
+                    stdin_file_count: stdinFileEntries.length,
+                    stdin_file_column_ids: stdinFileEntries.map((e) => e.columnId),
+                    hint: 'at most one `<file-col>=-` per call; source the other file ' +
+                        'columns from local paths.',
+                },
+            });
+        }
+        if (fileSetEntries.length > 1) {
+            throw new ApiError('usage_error', `A \`--set <file-col>=-\` stdin source must be the only file ` +
+                `\`--set\` entry in the call (stdin is a single stream — it ` +
+                `can't be combined with other file uploads in one invocation). ` +
+                `Run the stdin upload in its own call, or source every file ` +
+                `column from a local path.`, {
+                details: {
+                    reason: 'stdin_file_set_not_sole_file',
+                    file_count: fileSetEntries.length,
+                    stdin_file_column_id: firstStdin.columnId,
+                    file_column_ids: fileSetEntries.map((e) => e.columnId),
+                    hint: 'use `<file-col>=-` alone (e.g. `cat f | monday item set ' +
+                        '<iid> <file-col>=-`), or source all file columns from paths.',
+                },
+            });
+        }
+        if (inputs.callShape === 'item_update_bulk') {
+            throw new ApiError('usage_error', `\`--set <file-col>=-\` (stdin) is not supported on the bulk ` +
+                `\`monday item update --where ...\` path: stdin is a single ` +
+                `non-replayable stream and can't be fanned out across the ` +
+                `matched item set. Pipe to a temp file and \`--set ` +
+                `<file-col>=<path>\` for bulk, or target one item with ` +
+                `\`monday item update <iid> --set <file-col>=-\`.`, {
+                details: {
+                    reason: 'stdin_file_set_on_bulk_unsupported',
+                    column_id: firstStdin.columnId,
+                    call_shape: inputs.callShape,
+                    hint: 'stdin file `--set` is single-target only; use a local path ' +
+                        'for bulk fan-out or target a single item id.',
+                },
+            });
+        }
+    }
     // callShape gate — NO callShape short-circuits at this layer
     // post v0.7-M43. The v0.6-M38 `'item_create'` short-circuit-throw
     // (`'file_set_on_create_unsupported'`) FOLDED at v0.7-M43 (D6):
@@ -317,29 +583,41 @@ export const enforceSingleFileColumnSet = (inputs) => {
     // runtime rejection without a fresh contract decision. (Parallels
     // the v0.7-M42 fold of `'file_set_on_bulk_unsupported'` for
     // `'item_update_bulk'`.)
-    // Multi-file leg (D2 multi). 2+ file `--set` entries on any
-    // callShape — applies universally (single-item AND bulk) because
-    // Monday's `add_file_to_column` is single-column per call on the
-    // wire regardless of how many items the dispatch fans out across.
-    // Multi-file dispatch carries forward as a v0.7.x candidate.
-    if (fileSetEntries.length > 1) {
-        throw new ApiError('usage_error', `Multi-file \`--set <file-col>=<path>\` is not supported ` +
-            `(${String(fileSetEntries.length)} file \`--set\` entries ` +
-            `detected; deferred to v0.7.x per cli-design §5.3 + v0.6-plan ` +
-            `§3 M38 D2 closure — carry-forward from v0.6 unchanged at ` +
-            `v0.7-M42). Monday's \`add_file_to_column\` mutation is ` +
-            `single-column per call on the wire; multi-file dispatch + ` +
-            `concurrent multipart over the shared transport carry design ` +
-            `dimensions worth their own milestone. Pass exactly one ` +
-            `\`--set <file-col>=<path>\` per call; for multiple uploads, ` +
-            `run separate calls.`, {
+    // Multi-file leg (D2 multi). v0.8-M46 D2 carve-out fold: lifted
+    // on the 3 reachable callShapes (`'item_update_single'`,
+    // `'item_update_bulk'`, `'item_create'`); the action body routes
+    // the multi-file dispatch into the per-callShape multi-leg
+    // helper via the new `file_multi` / `file_bulk_multi` /
+    // `file_create_multi` enforcement kinds (see clean-leg block
+    // below).
+    //
+    // The `'item_set'` callShape's defensive throw stays in force —
+    // the single-positional `monday item set <iid> <col>=<value>`
+    // verb is argv-incapable of expressing 2+ file `--set` entries,
+    // so this branch is argv-unreachable in practice; kept as
+    // defense-in-depth + type-system ceiling. The
+    // `'multi_file_set_unsupported'` discriminator literal stays
+    // RESERVED across the codebase post-fold (mirrors v0.7-M42 D5
+    // fold of `'file_set_on_bulk_unsupported'` + v0.7-M43 D6 fold of
+    // `'file_set_on_create_unsupported'` reserved-literal discipline).
+    if (fileSetEntries.length > 1 && inputs.callShape === 'item_set') {
+        throw new ApiError('usage_error', `Multi-file \`--set <file-col>=<path>\` is not supported on the ` +
+            `\`monday item set\` single-positional verb (argv-unreachable ` +
+            `defensive guard — \`item set <iid> <col>=<value>\` accepts ` +
+            `exactly one positional). For multi-file dispatch, use ` +
+            `\`monday item update <iid> --set <file-col>=<path> --set ` +
+            `<file-col2>=<path2> ...\` (v0.8-M46 single-item multi-file ` +
+            `path) or \`monday item create --board <bid> --set ` +
+            `<file-col>=<path> --set <file-col2>=<path2> ...\` ` +
+            `(v0.8-M46 create-time multi-file path).`, {
             details: {
                 reason: 'multi_file_set_unsupported',
                 file_count: fileSetEntries.length,
                 file_column_ids: fileSetEntries.map((e) => e.columnId),
-                deferred_to: 'v0.7.x',
-                hint: 'pass exactly one `--set <file-col>=<path>` per call; ' +
-                    'run separate calls for multiple file uploads.',
+                call_shape: inputs.callShape,
+                hint: 'use `monday item update <iid> --set ...` or `monday item ' +
+                    'create --set ...` for multi-file dispatch (v0.8-M46 ' +
+                    'carve-out fold).',
             },
         });
     }
@@ -371,7 +649,7 @@ export const enforceSingleFileColumnSet = (inputs) => {
         const fe = fileSetEntries[0];
         /* c8 ignore next 3 */
         if (fe === undefined) {
-            throw new ApiError('internal_error', 'enforceSingleFileColumnSet: file entry narrowing failed (mixed)');
+            throw new ApiError('internal_error', 'routeFileColumnDispatch: file entry narrowing failed (mixed)');
         }
         throw new ApiError('usage_error', `Mixing a file \`--set <file-col>=<path>\` with value \`--set\` / ` +
             `\`--set-raw\` / \`--name\` in the same call is not supported at ` +
@@ -394,20 +672,88 @@ export const enforceSingleFileColumnSet = (inputs) => {
             },
         });
     }
-    // Clean dispatch leg. Single file `--set`, no mutex violation.
-    // Discriminators:
-    //   - `'item_update_single'` / `'item_set'` → `kind: 'file'`
-    //     (M38 single-item path; unchanged).
-    //   - `'item_update_bulk'` → `kind: 'file_bulk'` (v0.7-M42 D5
-    //     carve-out fold; action body's per-item multipart fan-out).
-    //   - `'item_create'` → `kind: 'file_create'` (v0.7-M43 D6
-    //     carve-out fold; action body's two-leg `create_item` then
-    //     `add_file_to_column` dispatch with orphan-warn atomicity
-    //     envelope per D1 closure).
+    // Clean dispatch leg. ≥1 file `--set`, no mutex violation.
+    // Branches on N (single vs multi) then on callShape:
+    //   N=1 (single-file path):
+    //     - `'item_update_single'` / `'item_set'` → `kind: 'file'`
+    //       (M38 single-item path; unchanged).
+    //     - `'item_update_bulk'` → `kind: 'file_bulk'` (v0.7-M42 D5
+    //       carve-out fold; action body's per-item multipart fan-out).
+    //     - `'item_create'` → `kind: 'file_create'` (v0.7-M43 D6
+    //       carve-out fold; action body's two-leg `create_item` then
+    //       `add_file_to_column` dispatch with orphan-warn atomicity
+    //       envelope per D1 closure).
+    //   N>1 (multi-file path — v0.8-M46 D2 carve-out fold):
+    //     - `'item_update_single'` → `kind: 'file_multi'` (single-item
+    //       N-leg fan-out helper `runItemUpdateSingleFileMultiDispatch`).
+    //     - `'item_update_bulk'` → `kind: 'file_bulk_multi'` (per-item
+    //       N-leg fan-out helper `runItemUpdateBulkFileMultiDispatch`;
+    //       cross-item parallel × within-item sequential).
+    //     - `'item_create'` → `kind: 'file_create_multi'` (two-leg-
+    //       group helper `runItemCreateFileMultiDispatch`; leg-1
+    //       `create_item` then N sequential `add_file_to_column`
+    //       legs). The `'item_set'` callShape is argv-unreachable
+    //       (single-positional; cannot express 2+ file `--set`) and
+    //       throws the defensive `'multi_file_set_unsupported'` above.
+    if (fileSetEntries.length > 1) {
+        // v0.8-M46 Codex R1 P2-1 fix: reject duplicate resolved file-
+        // column IDs across multi-file entries (mirrors JSON path's
+        // existing cross-token duplicate-resolved-ID contract at
+        // `src/api/resolution-pass.ts` + `docs/output-shapes.md`).
+        // Without this guard, `--set attachments=/p/a --set
+        // id:attachments=/p/b` (two distinct argv tokens that resolve
+        // to the same file column ID) would either silently dispatch
+        // two `add_file_to_column` legs against the same column (the
+        // second leg's file replaces the first wire-side — surprising
+        // behavior) or downstream `projectedEntries` token-by-find
+        // logic in `preCheckM38FileDispatch` would lose token identity
+        // (map both entries to the first token's slot). Rejecting at
+        // the enforcement layer is the simplest contract that aligns
+        // with the JSON path's existing behavior + sidesteps the
+        // token-identity edge case.
+        const seenColumnIds = new Set();
+        for (const entry of fileSetEntries) {
+            if (seenColumnIds.has(entry.columnId)) {
+                throw new ApiError('usage_error', `Multiple \`--set\` entries resolve to the same file column ` +
+                    `\`${entry.columnId}\` (v0.8-M46 multi-file dispatch requires ` +
+                    `each file column to appear at most once per call). Monday's ` +
+                    `\`add_file_to_column\` is single-column per call on the wire; ` +
+                    `two legs against the same column would either silently ` +
+                    `replace the first file or surface non-deterministic ` +
+                    `wire-side ordering. Drop one of the duplicate entries or ` +
+                    `target distinct file columns.`, {
+                    details: {
+                        reason: 'duplicate_resolved_file_columns',
+                        column_id: entry.columnId,
+                        file_count: fileSetEntries.length,
+                        file_column_ids: fileSetEntries.map((e) => e.columnId),
+                        hint: 'each file column may appear at most once across `--set` ' +
+                            'entries; drop the duplicate or target distinct file ' +
+                            'columns.',
+                    },
+                });
+            }
+            seenColumnIds.add(entry.columnId);
+        }
+        const entries = fileSetEntries.map((e) => ({
+            columnId: e.columnId,
+            rawValue: e.rawValue,
+        }));
+        if (inputs.callShape === 'item_update_bulk') {
+            return { kind: 'file_bulk_multi', entries };
+        }
+        if (inputs.callShape === 'item_create') {
+            return { kind: 'file_create_multi', entries };
+        }
+        // `'item_update_single'` (and `'item_set'` defensively — the
+        // multi-file gate above already threw on `'item_set'`, so this
+        // branch only fires for `'item_update_single'` in practice).
+        return { kind: 'file_multi', entries };
+    }
     const fe = fileSetEntries[0];
     /* c8 ignore next 3 */
     if (fe === undefined) {
-        throw new ApiError('internal_error', 'enforceSingleFileColumnSet: file entry narrowing failed (clean)');
+        throw new ApiError('internal_error', 'routeFileColumnDispatch: file entry narrowing failed (clean)');
     }
     if (inputs.callShape === 'item_update_bulk') {
         return { kind: 'file_bulk', columnId: fe.columnId, rawValue: fe.rawValue };
@@ -504,7 +850,7 @@ export const preCheckM38FileDispatch = async (inputs) => {
     // matters for the mutex check; columnId / columnType slots are
     // unused on the mixed-set discriminator path.
     const setRawEntries = Array.from({ length: inputs.setRawCount }, () => ({ columnId: '', columnType: '' }));
-    const enforcement = enforceSingleFileColumnSet({
+    const enforcement = routeFileColumnDispatch({
         callShape: inputs.callShape,
         setEntries: resolved.map((r) => ({
             columnId: r.columnId,
@@ -522,9 +868,41 @@ export const preCheckM38FileDispatch = async (inputs) => {
             cacheAgeSeconds: aggregateCacheAge,
         };
     }
-    // enforcement.kind is `'file'` (single-item) OR `'file_bulk'`
-    // (v0.7-M42 D5 carve-out fold). Find the matching resolved entry
-    // for the file-column token (echo into resolved_ids downstream).
+    // v0.8-M46 multi-file branches (D2 closure). The enforcement
+    // result carries a list of resolved file-column entries (length
+    // ≥ 2, argv order). Map each entry back to its argv token by
+    // matching (columnId, rawValue) against the pre-check's
+    // `resolved` list — the token is the load-bearing handle for
+    // the dispatch envelope's `resolved_ids` slot.
+    if (enforcement.kind === 'file_multi' ||
+        enforcement.kind === 'file_bulk_multi' ||
+        enforcement.kind === 'file_create_multi') {
+        const projectedEntries = enforcement.entries.map((entry) => {
+            const fileResolved = resolved.find((r) => r.columnType === 'file' &&
+                r.columnId === entry.columnId &&
+                r.rawValue === entry.rawValue);
+            /* c8 ignore next 6 — defensive: enforcement returned entries
+               the pre-check passed in; every find must succeed. */
+            if (fileResolved === undefined) {
+                throw new ApiError('internal_error', 'preCheckM38FileDispatch: multi-file entry not found in resolved set after enforcement');
+            }
+            return {
+                columnId: entry.columnId,
+                rawValue: entry.rawValue,
+                token: fileResolved.token,
+            };
+        });
+        return {
+            kind: enforcement.kind,
+            entries: projectedEntries,
+            warnings,
+            source: aggregateSource,
+            cacheAgeSeconds: aggregateCacheAge,
+        };
+    }
+    // Single-file branches: `'file'` (M38) / `'file_bulk'` (M42) /
+    // `'file_create'` (M43). Find the matching resolved entry for
+    // the file-column token (echo into resolved_ids downstream).
     const fileResolved = resolved.find((r) => r.columnType === 'file' &&
         r.columnId === enforcement.columnId &&
         r.rawValue === enforcement.rawValue);