@datarails-ai/dr-cli 1.6.96 → 1.6.98

package/README.md

@@ -230,6 +230,20 @@ under one identity and run as another.
 { "apiKey": "<key>", "server": "DEV", "email": "svc@datarails.com" }
 ```
 
+The key may instead live in an environment variable, with the file carrying
+only the variable's **name** — the shape for CI (the key stays in the runner's
+secret env, never on disk) and for agent sandboxes (where the variable's
+in-sandbox value is an opaque vault placeholder substituted at egress, passed
+verbatim and never validated):
+
+```json
+{ "apiKeyEnvVar": "DR_API_KEY", "server": "DEV", "email": "svc@datarails.com" }
+```
+
+`apiKey` and `apiKeyEnvVar` are mutually exclusive — a file carrying both is
+refused rather than guessed about. An unset variable fails the command with an
+error naming it; the stored file is never modified by that failure.
+
 `email` names the stored identity — what `--account` selects and what the
 keychain entry is keyed by. It need not match the principal the key is bound to;
 the token the exchange mints is what every request authenticates as, and

package/dist/cli.js

@@ -8,7 +8,7 @@ import { fileURLToPath as fileURLToPath3 } from "url";
 // package.json
 var package_default = {
   name: "@datarails-ai/dr-cli",
-  version: "1.6.96",
+  version: "1.6.98",
   description: "Datarails CLI",
   type: "module",
   engines: {
@@ -38,7 +38,7 @@ var package_default = {
     postinstall: "node scripts/postinstall.mjs"
   },
   dependencies: {
-    "@datarails-ai/dr-appspace-cli": "0.10.20",
+    "@datarails-ai/dr-appspace-cli": "0.10.21",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "^1.3.0",
     commander: "^12.1.0",
@@ -67,7 +67,7 @@ var package_default = {
 };
 
 // src/buildInfo.ts
-var BUILD_TIME = "2026-10-04T14:30:08.766Z";
+var BUILD_TIME = "2026-10-05T10:25:04.884Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -151,14 +151,17 @@ function parseApiKeyExpiry(value) {
 function hasApiKey(s) {
   return s.apiKey !== void 0 && s.apiKey !== "";
 }
+function hasApiKeyEnvVar(s) {
+  return s.apiKeyEnvVar !== void 0 && s.apiKeyEnvVar !== "";
+}
 function isImpersonatedSession(s) {
   return s.impersonatorEmail !== void 0 && s.impersonatorEmail !== "";
 }
 function isCookielessSession(s) {
-  return isImpersonatedSession(s) || s.cookieless === true || hasApiKey(s);
+  return isImpersonatedSession(s) || s.cookieless === true || hasApiKey(s) || hasApiKeyEnvVar(s);
 }
 function usesApiKey(s) {
-  return hasApiKey(s) && !isImpersonatedSession(s);
+  return (hasApiKey(s) || hasApiKeyEnvVar(s)) && !isImpersonatedSession(s);
 }
 var KeychainError = class extends Error {
   constructor(message, options) {
@@ -294,6 +297,16 @@ var credentialsFileSchema = z.object({
   // A user-bound API key, exchanged for `access` on demand. A file may hold
   // only this; `access` then appears after the first exchange.
   apiKey: z.string().min(1).optional(),
+  // DR-52657: the NAME of an environment variable holding the API key, for
+  // provisioners that must not put the key on disk — an agent sandbox, where
+  // the variable's in-sandbox value is an opaque vault placeholder
+  // substituted at egress, or a CI runner keeping the key in its secret env.
+  // The value is resolved at exchange time and passed verbatim; dr-cli never
+  // inspects, validates, or logs it. Mutually exclusive with `apiKey` (a
+  // refinement below): a file carrying both is ambiguous about which
+  // credential authenticates it, and silently preferring either one turns a
+  // provisioning mistake into commands running as the wrong key.
+  apiKeyEnvVar: z.string().min(1).optional(),
   // Carried verbatim, judged by `parseApiKeyExpiry` where it is read. Not
   // validated here, and not `.catch(undefined)` either: a rotation rewrites
   // the whole file from the parsed object, so a value this schema dropped
@@ -332,13 +345,19 @@ var credentialsFileSchema = z.object({
 }).passthrough().refine((c) => c.sessionId === void 0 === (c.csrfToken === void 0), {
   message: "sessionId and csrfToken must be provided together",
   path: ["sessionId"]
-}).refine((c) => c.access !== void 0 || c.apiKey !== void 0, {
-  message: "one of access or apiKey is required",
+}).refine((c) => !(c.apiKey !== void 0 && c.apiKeyEnvVar !== void 0), {
+  message: "apiKey and apiKeyEnvVar are mutually exclusive",
+  path: ["apiKeyEnvVar"]
+}).refine((c) => c.access !== void 0 || c.apiKey !== void 0 || c.apiKeyEnvVar !== void 0, {
+  message: "one of access, apiKey or apiKeyEnvVar is required",
   path: ["access"]
-}).refine((c) => c.apiKey !== void 0 || c.refresh !== void 0 || c.sessionId !== void 0, {
-  message: "refresh is required unless an apiKey or a session cookie is present",
-  path: ["refresh"]
-});
+}).refine(
+  (c) => c.apiKey !== void 0 || c.apiKeyEnvVar !== void 0 || c.refresh !== void 0 || c.sessionId !== void 0,
+  {
+    message: "refresh is required unless an apiKey, apiKeyEnvVar or a session cookie is present",
+    path: ["refresh"]
+  }
+);
 function credentialsFilePath() {
   const override = process.env[CREDENTIALS_FILE_ENV];
   return override !== void 0 && override !== "" ? override : DEFAULT_CREDENTIALS_FILE;
@@ -801,7 +820,13 @@ async function exchangeApiKey(host, apiKey, options) {
   if (key === "") {
     throw new Error("api-key exchange: the stored API key is empty");
   }
-  if (!/^[\x21-\x7e]+$/.test(key)) {
+  if (options?.opaque === true) {
+    if (/[\r\n\0]/.test(key) || !/^[\x00-\xff]+$/.test(key)) {
+      throw new Error(
+        "api-key exchange: the environment variable named by apiKeyEnvVar holds a value that cannot travel in an HTTP header (a line break, NUL, or a character above U+00FF)"
+      );
+    }
+  } else if (!/^[\x21-\x7e]+$/.test(key)) {
     throw new Error(
       "api-key exchange: dr only accepts an API key of printable ASCII with no spaces; the stored one contains whitespace, control characters, or non-ASCII characters"
     );
@@ -965,10 +990,31 @@ function mintedByApiKey(token) {
 function apiKeyFingerprint(apiKey) {
   return createHash("sha256").update(apiKey.trim()).digest("hex").slice(0, 32);
 }
+function resolveApiKeyMaterial(session) {
+  if (session.apiKey !== void 0 && session.apiKey !== "") {
+    return { key: session.apiKey, fromEnv: false };
+  }
+  const name = session.apiKeyEnvVar;
+  if (name === void 0 || name === "") {
+    throw new Error("api-key exchange: the session carries no API key");
+  }
+  const value = process.env[name];
+  if (value === void 0 || value === "") {
+    throw new Error(
+      `api-key exchange: the credential file names environment variable ${name} as the API-key carrier, but it is unset or empty in this environment`
+    );
+  }
+  return { key: value, fromEnv: true };
+}
 function mintedByStoredApiKey(session) {
   if (!mintedByApiKey(session.jwtAccess)) return false;
-  if (session.apiKey === void 0 || session.apiKey === "") return false;
-  return session.jwtApiKeyFingerprint === apiKeyFingerprint(session.apiKey);
+  let material;
+  try {
+    material = resolveApiKeyMaterial(session);
+  } catch {
+    return false;
+  }
+  return session.jwtApiKeyFingerprint === apiKeyFingerprint(material.key);
 }
 function apiKeyStaleBuffer(session, identity2, fallbackMs) {
   if (session.jwtAccess === void 0 || session.jwtAccess === "") return fallbackMs;
@@ -995,12 +1041,13 @@ function ttlOf(token) {
 function exchangeForSession(store, serverKey, email, session, host, opts) {
   const identity2 = `${serverKey}:${email}`;
   if (opts.signal?.aborted === true) return Promise.reject(opts.signal.reason);
-  const key = JSON.stringify([
-    identity2,
-    host,
-    opts.force,
-    apiKeyFingerprint(session.apiKey)
-  ]);
+  let material;
+  try {
+    material = resolveApiKeyMaterial(session);
+  } catch (err) {
+    throw new SessionExpiredError(`${identity2} (${msgOf3(err)})`);
+  }
+  const key = JSON.stringify([identity2, host, opts.force, apiKeyFingerprint(material.key)]);
   const pending = inFlightExchanges.get(key);
   if (pending !== void 0) return joinExchange(pending, opts.signal);
   const controller = new AbortController();
@@ -1015,7 +1062,7 @@ function exchangeForSession(store, serverKey, email, session, host, opts) {
     for (; ; ) {
       let tok;
       try {
-        tok = await exchangeApiKey(host, session.apiKey, { signal });
+        tok = await exchangeApiKey(host, material.key, { signal, opaque: material.fromEnv });
       } catch (err) {
         const cachedIsUsable = !opts.force && mintedByStoredApiKey(session) && !jwtExpiringSoon(session, 0);
         if (!(err instanceof ApiKeyExchangeError)) {
@@ -1054,7 +1101,7 @@ function exchangeForSession(store, serverKey, email, session, host, opts) {
         // the token did not come from. Read back by `mintedByStoredApiKey` on
         // every later command to tell this token apart from one the previous
         // key minted.
-        jwtApiKeyFingerprint: apiKeyFingerprint(session.apiKey),
+        jwtApiKeyFingerprint: apiKeyFingerprint(material.key),
         // Dropped, not carried: the exchange mints no refresh token, and the
         // refresh rung is closed to a keyed identity by contract. Clearing it
         // is what lets "keyed, and still holding a refresh token" mean "these
@@ -1065,7 +1112,7 @@ function exchangeForSession(store, serverKey, email, session, host, opts) {
       };
       try {
         const current = await store.getSession(serverKey, email);
-        if (current === void 0 || current.apiKey !== session.apiKey) {
+        if (current === void 0 || current.apiKey !== session.apiKey || current.apiKeyEnvVar !== session.apiKeyEnvVar) {
           return next;
         }
         await store.saveSession(serverKey, next);
@@ -1383,7 +1430,8 @@ var KeyringStore = class _KeyringStore {
     const impersonated = impersonatorEmail !== "";
     const cookielessFlag = parsed2.cookieless === true;
     const apiKey = await this.backend.get(SERVICE, `${sessionAccount}:apikey`);
-    const keyPresent = apiKey !== void 0 && apiKey !== "";
+    const apiKeyEnvVar = typeof parsed2.apiKeyEnvVar === "string" ? parsed2.apiKeyEnvVar : "";
+    const keyPresent = apiKey !== void 0 && apiKey !== "" || apiKeyEnvVar !== "";
     const cookieless = impersonated || cookielessFlag || keyPresent;
     const halfCookie = sessionId === "" !== (csrfToken === "");
     if (savedAtStr === "" || halfCookie || !cookieless && sessionId === "") {
@@ -1429,9 +1477,12 @@ var KeyringStore = class _KeyringStore {
     if (jwtRefresh !== void 0 && jwtRefresh !== "") {
       session.jwtRefresh = jwtRefresh;
     }
-    if (keyPresent) {
+    if (apiKey !== void 0 && apiKey !== "") {
       session.apiKey = apiKey;
     }
+    if (apiKeyEnvVar !== "") {
+      session.apiKeyEnvVar = apiKeyEnvVar;
+    }
     return session;
   }
   /**
@@ -1463,9 +1514,9 @@ var KeyringStore = class _KeyringStore {
     const impersonated = isImpersonatedSession(session);
     if (isCookielessSession(session)) {
       const hasJwt = session.jwtAccess !== void 0 && session.jwtAccess !== "";
-      if (!hasJwt && !hasApiKey(session)) {
+      if (!hasJwt && !hasApiKey(session) && !hasApiKeyEnvVar(session)) {
         throw new Error(
-          "saveSession: cookie-less session must have a jwtAccess token or an apiKey"
+          "saveSession: cookie-less session must have a jwtAccess token, an apiKey, or an apiKeyEnvVar"
         );
       }
       if (session.sessionId === "" !== (session.csrfToken === "")) {
@@ -1496,6 +1547,9 @@ var KeyringStore = class _KeyringStore {
     if (session.jwtApiKeyFingerprint !== void 0 && session.jwtApiKeyFingerprint !== "") {
       metaBlob.jwtApiKeyFingerprint = session.jwtApiKeyFingerprint;
     }
+    if (hasApiKeyEnvVar(session)) {
+      metaBlob.apiKeyEnvVar = session.apiKeyEnvVar;
+    }
     if (impersonated) {
       metaBlob.impersonatorEmail = session.impersonatorEmail;
       if (session.impersonatedUserId !== void 0) {
@@ -2599,7 +2653,9 @@ var FileKeyringBackend = class _FileKeyringBackend {
       // Named as the Session field, since the blob is what `getSession` reads.
       ...creds.accessApiKeyFingerprint !== void 0 && {
         jwtApiKeyFingerprint: creds.accessApiKeyFingerprint
-      }
+      },
+      // The env var's NAME only — the resolved key never enters any store.
+      ...creds.apiKeyEnvVar !== void 0 && { apiKeyEnvVar: creds.apiKeyEnvVar }
     });
   }
   static slotOf(creds, account) {
@@ -2627,11 +2683,16 @@ var FileKeyringBackend = class _FileKeyringBackend {
     const csrfToken = typeof parsed2.csrfToken === "string" ? parsed2.csrfToken : "";
     const apiKeyExpiresAt = typeof parsed2.apiKeyExpiresAt === "string" ? parsed2.apiKeyExpiresAt : "";
     const accessApiKeyFingerprint = typeof parsed2.jwtApiKeyFingerprint === "string" ? parsed2.jwtApiKeyFingerprint : "";
+    const apiKeyEnvVar = typeof parsed2.apiKeyEnvVar === "string" ? parsed2.apiKeyEnvVar : "";
     return {
       ...sessionId !== "" && { sessionId },
       ...csrfToken !== "" && { csrfToken },
       ...apiKeyExpiresAt !== "" && { apiKeyExpiresAt },
-      ...accessApiKeyFingerprint !== "" && { accessApiKeyFingerprint }
+      ...accessApiKeyFingerprint !== "" && { accessApiKeyFingerprint },
+      // Set-if-present, never deleted on a blob that lost it (the
+      // `apiKeyExpiresAt` rule): it is the identity's only credential pointer,
+      // and a meta rewrite must not be able to brick the file.
+      ...apiKeyEnvVar !== "" && { apiKeyEnvVar }
     };
   }
   async get(_service, account) {
@@ -2724,6 +2785,7 @@ var FileKeyringBackend = class _FileKeyringBackend {
             if (meta.apiKeyExpiresAt !== void 0) next.apiKeyExpiresAt = meta.apiKeyExpiresAt;
             if (meta.accessApiKeyFingerprint === void 0) delete next.accessApiKeyFingerprint;
             else next.accessApiKeyFingerprint = meta.accessApiKeyFingerprint;
+            if (meta.apiKeyEnvVar !== void 0) next.apiKeyEnvVar = meta.apiKeyEnvVar;
             break;
           }
         }
@@ -3624,6 +3686,10 @@ var PROD_GATE_TIER_B = /* @__PURE__ */ new Set([
   // tier so a CSM or agent can run a MEC implementation's bulk assignment on
   // prod (DR-54064).
   "recon-member-batch|set",
+  // clear-assignee --file: N `recon-member|clear` writes under one token, same
+  // reasoning — each is undone by set-assignee, already-empty slots are
+  // skipped, and the plan shows the sign-offs it resets (DR-54260).
+  "recon-member-batch|clear",
   "recon-member|clear",
   "recon-member|set-due-date",
   "recon-member|sign",
@@ -42254,31 +42320,51 @@ function validateRow(row, idx) {
 
 // src/commands/_reconciliationAssigneeCsv.ts
 import { promises as fs17 } from "fs";
-var REQUIRED_COLUMNS = ["account_id", "type", "user_id"];
-var OPTIONAL_COLUMNS = ["user_name", "user_email"];
-var KNOWN_COLUMNS = /* @__PURE__ */ new Set([...REQUIRED_COLUMNS, ...OPTIONAL_COLUMNS]);
+var ASSIGNEE_REQUIRED = ["account_id", "type", "user_id"];
+var ASSIGNEE_OPTIONAL = ["user_name", "user_email"];
+var CLEAR_REQUIRED = ["account_id", "type"];
 async function readAssigneeCsv(path11) {
-  let raw;
+  return parseAssigneeCsvText(await readFileArg(path11));
+}
+async function readClearAssigneeCsv(path11) {
+  return parseClearAssigneeCsvText(await readFileArg(path11));
+}
+async function readFileArg(path11) {
   try {
-    raw = await fs17.readFile(path11, "utf8");
+    return await fs17.readFile(path11, "utf8");
   } catch (err) {
     const m = err instanceof Error ? err.message : String(err);
     throw new Error(`read --file: ${m}`);
   }
-  return parseAssigneeCsvText(raw);
 }
 function parseAssigneeCsvText(text2) {
+  return parseSlotRows(text2, ASSIGNEE_REQUIRED, ASSIGNEE_OPTIONAL, (slot, cell) => {
+    const rawUserId = cell("user_id");
+    const userId = Number(rawUserId);
+    if (!/^\d+$/.test(rawUserId) || !Number.isSafeInteger(userId) || userId <= 0) {
+      throw new Error(
+        `--file: line ${slot.lineNo}: invalid user_id "${rawUserId}" (expected positive integer)`
+      );
+    }
+    return { ...slot, userId, userName: cell("user_name"), userEmail: cell("user_email") };
+  });
+}
+function parseClearAssigneeCsvText(text2) {
+  return parseSlotRows(text2, CLEAR_REQUIRED, [], (slot) => slot);
+}
+function parseSlotRows(text2, required2, optional, extra) {
   const withoutBom = text2.charCodeAt(0) === 65279 ? text2.slice(1) : text2;
   const rows = parseCsvRows(withoutBom);
   if (rows.length === 0) {
     throw new Error("--file: CSV is empty");
   }
+  const known = /* @__PURE__ */ new Set([...required2, ...optional]);
   const header = rows[0].map((h) => h.trim());
   const col = /* @__PURE__ */ new Map();
   header.forEach((h, i) => {
-    if (!KNOWN_COLUMNS.has(h)) {
+    if (!known.has(h)) {
       throw new Error(
-        `--file: unknown CSV column "${h}" \u2014 expected ${[...REQUIRED_COLUMNS, ...OPTIONAL_COLUMNS].join(",")}`
+        `--file: unknown CSV column "${h}" \u2014 expected ${[...required2, ...optional].join(",")}`
       );
     }
     if (col.has(h)) {
@@ -42286,7 +42372,7 @@ function parseAssigneeCsvText(text2) {
     }
     col.set(h, i);
   });
-  for (const c of REQUIRED_COLUMNS) {
+  for (const c of required2) {
     if (!col.has(c)) {
       throw new Error(`--file: CSV header is missing required column "${c}"`);
     }
@@ -42295,30 +42381,24 @@ function parseAssigneeCsvText(text2) {
   if (dataRows.length === 0) {
     throw new Error("--file: CSV has no data rows (header only)");
   }
-  const cell = (cells, name) => {
-    const i = col.get(name);
-    return i === void 0 ? "" : (cells[i] ?? "").trim();
-  };
   const seenSlots = /* @__PURE__ */ new Map();
   const out = [];
   for (const { cells, lineNo } of dataRows) {
-    const accountId = cell(cells, "account_id");
+    const cell = (name) => {
+      const i = col.get(name);
+      return i === void 0 ? "" : (cells[i] ?? "").trim();
+    };
+    const accountId = cell("account_id");
     if (accountId === "") {
       throw new Error(`--file: line ${lineNo}: "account_id" is required`);
     }
-    const rawType = cell(cells, "type");
+    const rawType = cell("type");
     if (rawType !== "Preparer" && rawType !== "Reviewer") {
       throw new Error(
         `--file: line ${lineNo}: invalid type "${rawType}" (expected "Preparer" or "Reviewer")`
       );
     }
-    const rawUserId = cell(cells, "user_id");
-    const userId = Number(rawUserId);
-    if (!/^\d+$/.test(rawUserId) || !Number.isSafeInteger(userId) || userId <= 0) {
-      throw new Error(
-        `--file: line ${lineNo}: invalid user_id "${rawUserId}" (expected positive integer)`
-      );
-    }
+    const row = extra({ lineNo, accountId, type: rawType }, cell);
     const slot = `${accountId}:${rawType}`;
     const prior = seenSlots.get(slot);
     if (prior !== void 0) {
@@ -42327,14 +42407,7 @@ function parseAssigneeCsvText(text2) {
       );
     }
     seenSlots.set(slot, lineNo);
-    out.push({
-      lineNo,
-      accountId,
-      type: rawType,
-      userId,
-      userName: cell(cells, "user_name"),
-      userEmail: cell(cells, "user_email")
-    });
+    out.push(row);
   }
   return out;
 }
@@ -44025,52 +44098,186 @@ verify the date matches the accounts' reporting period (try \`dr reconciliation
         account_id: id,
         members: applyAssignments(byId.get(id), changesByAccount.get(id))
       }));
-      extendForBatch(cfg.extendTimeout, requests * 2 - 1);
-      let applied = 0;
-      for (let i = 0; i < items.length; i += chunkSize) {
-        const chunk = items.slice(i, i + chunkSize);
-        if (i > 0) {
-          let drift;
-          try {
-            drift = await chunkDrift(cfg, byId, chunk);
-          } catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            throw new Error(
-              `re-read failed after ${applied} of ${items.length} account${plural(items.length)} were written; nothing more was sent: ${msg}
-Re-run the same command without --confirm-token: rows that landed plan as unchanged, so the new plan covers only the rest.`
-            );
-          }
-          if (drift.length > 0) {
-            throw new Error(
-              `halted after ${applied} of ${items.length} account${plural(items.length)} were written; nothing more was sent:
-  ` + drift.join("\n  ") + `
-The tenant changed since the plan. Re-run the same command without --confirm-token: rows that landed plan as unchanged. If accounts are gone, the trial balance was rebuilt and their ids changed \u2014 wait for it to settle and rebuild the file from \`dr reconciliation accounts list\`.`
+      const applied = await writeMemberChunks(cfg, byId, items, chunkSize);
+      if (cfg.asJson) {
+        const changed = accountIds.flatMap((id) => changesByAccount.get(id).map(toJsonRow));
+        writeJSONIndented(cfg.out, { changed, unchanged: unchanged.map(toJsonRow) });
+        return;
+      }
+      cfg.out.write(
+        `Set ${changeCount} role${plural(changeCount)} on ${applied} account${plural(applied)} (${unchanged.length} unchanged).
+`
+      );
+    }
+  });
+}
+function clearBatchActionId(date, rows) {
+  const canonical = rows.map((r) => [r.accountId, r.type]);
+  return createHash8("sha256").update(JSON.stringify(["clear", date, canonical])).digest("hex").slice(0, 12);
+}
+async function runReconciliationAccountsClearAssigneeBatch(cfg) {
+  const action = {
+    resource: "recon-member-batch",
+    id: clearBatchActionId(cfg.date, cfg.rows),
+    verb: "clear"
+  };
+  await preflightConfirmToken(action, cfg.token);
+  extendForBatch(cfg.extendTimeout, 1);
+  const accounts = await getAccounts(
+    cfg.client,
+    { date: cfg.date },
+    { signal: cfg.signal }
+  );
+  const byId = new Map(accounts.map((a) => [a.account_id, a]));
+  const problems = [];
+  for (const row of cfg.rows) {
+    const account = byId.get(row.accountId);
+    if (account === void 0) {
+      problems.push(`line ${row.lineNo}: account "${row.accountId}" not found at --date`);
+    } else if (account.members.length > 0 && !account.members.some((m) => m.type === row.type)) {
+      problems.push(
+        `line ${row.lineNo}: account "${row.accountId}" has a partial member set (${account.members.map((m) => m.type).join(", ")}) and is missing ${row.type}`
+      );
+    }
+  }
+  if (problems.length > 0) {
+    const shown = problems.slice(0, 10);
+    const more = problems.length > 10 ? [`\u2026 (+${problems.length - 10} more)`] : [];
+    throw new Error(
+      `--file: ${problems.length} row${plural(problems.length)} cannot be applied; nothing was written:
+  ` + [...shown, ...more].join("\n  ") + `
+verify the date matches the accounts' reporting period (try \`dr reconciliation accounts list --date \u2026\`)`
+    );
+  }
+  const clearsByAccount = /* @__PURE__ */ new Map();
+  const unchanged = [];
+  for (const row of cfg.rows) {
+    const current = byId.get(row.accountId).members.find((m) => m.type === row.type);
+    if (current === void 0 || current.user_id === 0) {
+      unchanged.push(row);
+      continue;
+    }
+    const list28 = clearsByAccount.get(row.accountId) ?? [];
+    list28.push({ row, current });
+    clearsByAccount.set(row.accountId, list28);
+  }
+  const clearCount = cfg.rows.length - unchanged.length;
+  const n = cfg.rows.length;
+  if (clearCount === 0) {
+    if (cfg.asJson) {
+      writeJSONIndented(cfg.out, {
+        changed: [],
+        unchanged: unchanged.map((r) => ({ account_id: r.accountId, type: r.type }))
+      });
+      return;
+    }
+    cfg.out.write(
+      `Nothing to clear: all ${n} row${plural(n)} name a slot that is already Unassigned or does not exist yet.
+`
+    );
+    return;
+  }
+  const chunkSize = cfg.chunkSize ?? ASSIGNEE_BATCH_CHUNK_SIZE;
+  const accountIds = [...clearsByAccount.keys()];
+  const requests = Math.ceil(accountIds.length / chunkSize);
+  await twoStepConfirm({
+    out: cfg.out,
+    action,
+    token: cfg.token,
+    server: cfg.serverFlag,
+    confirmCmd: cfg.confirmCmd,
+    describe: async () => {
+      let signOffsReset = 0;
+      const preview = [];
+      for (const id of accountIds) {
+        const account = byId.get(id);
+        for (const { row, current } of clearsByAccount.get(id)) {
+          if (current.is_sign_off) signOffsReset += 1;
+          if (preview.length < 5) {
+            preview.push(
+              `  ${account.account_name} (${id}) ${row.type}: ${current.name} (user ${current.user_id}) \u2192 Unassigned`
             );
           }
         }
-        try {
-          await updateAccountMembers(cfg.client, chunk, { signal: cfg.signal });
-        } catch (err) {
-          const msg = err instanceof Error ? err.message : String(err);
-          throw new Error(
-            `PATCH failed after ${applied} of ${items.length} account${plural(items.length)} were written (accounts ${i + 1}\u2013${i + chunk.length} may be partially applied): ${msg}
-Re-run the same command without --confirm-token: rows that landed plan as unchanged, so the new plan covers only the rest.`
-          );
-        }
-        applied += chunk.length;
       }
+      const lines = [
+        `rows:      ${n}`,
+        `to clear:  ${clearCount} role${plural(clearCount)} on ${accountIds.length} account${plural(accountIds.length)} (${requests} PATCH request${plural(requests)})`,
+        `unchanged: ${unchanged.length} (slot already Unassigned, or the account has no member slots \u2014 skipped)`,
+        `sign-offs reset: ${signOffsReset}`,
+        "changes:",
+        ...preview
+      ];
+      if (clearCount > preview.length) lines.push(`  \u2026 (+${clearCount - preview.length} more)`);
+      return lines;
+    },
+    execute: async () => {
+      const items = accountIds.map((id) => {
+        const cleared = new Set(clearsByAccount.get(id).map((c) => c.row.type));
+        return {
+          account_id: id,
+          members: byId.get(id).members.map(
+            (m) => cleared.has(m.type) ? unassignedMember(m.type, m.due_date) : memberSummaryToWire(m)
+          )
+        };
+      });
+      const applied = await writeMemberChunks(cfg, byId, items, chunkSize);
       if (cfg.asJson) {
-        const changed = accountIds.flatMap((id) => changesByAccount.get(id).map(toJsonRow));
-        writeJSONIndented(cfg.out, { changed, unchanged: unchanged.map(toJsonRow) });
+        writeJSONIndented(cfg.out, {
+          changed: accountIds.flatMap(
+            (id) => clearsByAccount.get(id).map(({ row, current }) => ({
+              account_id: row.accountId,
+              type: row.type,
+              previous_user_id: current.user_id
+            }))
+          ),
+          unchanged: unchanged.map((r) => ({ account_id: r.accountId, type: r.type }))
+        });
         return;
       }
       cfg.out.write(
-        `Set ${changeCount} role${plural(changeCount)} on ${applied} account${plural(applied)} (${unchanged.length} unchanged).
+        `Cleared ${clearCount} role${plural(clearCount)} on ${applied} account${plural(applied)} (${unchanged.length} unchanged).
 `
       );
     }
   });
 }
+async function writeMemberChunks(ctx, planned, items, chunkSize) {
+  const requests = Math.ceil(items.length / chunkSize);
+  extendForBatch(ctx.extendTimeout, requests * 2);
+  let applied = 0;
+  for (let i = 0; i < items.length; i += chunkSize) {
+    const chunk = items.slice(i, i + chunkSize);
+    let drift;
+    try {
+      drift = await chunkDrift(ctx, planned, chunk);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `re-read failed after ${applied} of ${items.length} account${plural(items.length)} were written; nothing more was sent: ${msg}
+Re-run the same command without --confirm-token: rows that landed plan as unchanged, so the new plan covers only the rest.`
+      );
+    }
+    if (drift.length > 0) {
+      throw new Error(
+        `halted after ${applied} of ${items.length} account${plural(items.length)} were written; nothing more was sent:
+  ` + drift.join("\n  ") + `
+The tenant changed since the plan. Re-run the same command without --confirm-token: rows that landed plan as unchanged. If accounts are gone, the trial balance was rebuilt and their ids changed \u2014 wait for it to settle and rebuild the file from \`dr reconciliation accounts list\`.`
+      );
+    }
+    try {
+      await updateAccountMembers(ctx.client, chunk, { signal: ctx.signal });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `PATCH failed after ${applied} of ${items.length} account${plural(items.length)} were written (accounts ${i + 1}\u2013${i + chunk.length} may be partially applied): ${msg}
+Re-run the same command without --confirm-token: rows that landed plan as unchanged, so the new plan covers only the rest.`
+      );
+    }
+    applied += chunk.length;
+  }
+  return applied;
+}
 async function chunkDrift(cfg, planned, chunk) {
   const now = await getAccounts(cfg.client, { date: cfg.date }, { signal: cfg.signal });
   const nowById = new Map(now.map((a) => [a.account_id, a]));
@@ -44579,16 +44786,69 @@ function wireReconciliation(program) {
   );
   addServerFlag(setAssigneeCmd);
   addAccountFlag(setAssigneeCmd);
-  const clearAssigneeCmd = accounts.command("clear-assignee").description(
-    "Clear the Preparer or Reviewer slot (sets user_id=0 + Unassigned name/email; preserves due_date, resets sign-off)"
-  ).argument("<account_uuid>", "account uuid").requiredOption("--date <YYYY-MM-DD>", "Reporting date").requiredOption("--type <s>", "Preparer | Reviewer (case-sensitive)").option("--json", "Output the cleared member record as JSON instead of a confirmation", false).option(
+  const clearAssigneeCmd = accounts.command("clear-assignee").summary("Clear the Preparer or Reviewer slot of one account, or many with --file").description(
+    [
+      "Clear the Preparer or Reviewer slot (sets user_id=0 + Unassigned name/email; preserves due_date, resets sign-off)",
+      "",
+      "Bulk form \u2014 one plan and one token for many slots:",
+      "  dr reconciliation accounts clear-assignee --file slots.csv --date 2025-04-30",
+      "  # CSV header: account_id,type \u2014 one row per (account, role)"
+    ].join("\n")
+  ).argument("[account_uuid]", "account uuid; omit with --file").requiredOption("--date <YYYY-MM-DD>", "Reporting date").option("--type <s>", "Preparer | Reviewer (case-sensitive); required without --file").option(
+    "--file <path>",
+    "CSV of slots to clear (header account_id,type); one plan + one token for the whole file"
+  ).option(
+    "--json",
+    "Output the cleared member record(s) as JSON instead of a confirmation",
+    false
+  ).option("--timeout <seconds>", `With --file: ${BATCH_TIMEOUT_FLAG_HELP}`).option(
     "--confirm-token <token>",
     "Token from a prior plan run \u2014 required to actually clear",
     ""
   ).action(
     async (accountUuid, opts) => {
       const date = parseDateFlag(opts.date ?? "", "--date");
-      const type = parseMemberTypeFlag(opts.type ?? "", "--type");
+      if (opts.file !== void 0) {
+        const conflicting = [
+          accountUuid !== void 0 ? "<account_uuid>" : "",
+          opts.type !== void 0 ? "--type" : ""
+        ].filter((s) => s !== "");
+        if (conflicting.length > 0) {
+          throw new Error(
+            `--file cannot be combined with ${conflicting.join(", ")} (the CSV carries them per row)`
+          );
+        }
+        const rows = await readClearAssigneeCsv(opts.file);
+        await preflightConfirmToken(
+          { resource: "recon-member-batch", id: clearBatchActionId(date, rows), verb: "clear" },
+          opts.confirmToken
+        );
+        const serverKey2 = resolveServer(opts.server);
+        const confirmCmd2 = `dr reconciliation accounts clear-assignee --file ${JSON.stringify(opts.file)} --date ${opts.date}` + (opts.json === true ? " --json" : "") + (opts.timeout !== void 0 ? ` --timeout ${opts.timeout}` : "") + ` --server ${serverKey2}`;
+        const setup2 = await setupCall(opts.server, opts.account, batchSetupOptions(opts.timeout));
+        try {
+          await runReconciliationAccountsClearAssigneeBatch({
+            client: setup2.client,
+            extendTimeout: setup2.extendTimeout,
+            date,
+            rows,
+            token: opts.confirmToken,
+            confirmCmd: confirmCmd2,
+            serverFlag: serverKey2,
+            asJson: opts.json === true,
+            signal: setup2.signal,
+            out: process.stdout
+          });
+        } finally {
+          setup2.cleanup();
+        }
+        return;
+      }
+      if (accountUuid === void 0) {
+        throw new Error("missing <account_uuid> (or pass --file <csv> for many slots)");
+      }
+      if (opts.type === void 0) throw new Error("required option '--type <s>' not specified");
+      const type = parseMemberTypeFlag(opts.type, "--type");
       await preflightConfirmToken(
         {
           resource: "recon-member",
@@ -44749,7 +45009,7 @@ import * as nodePath2 from "path";
 var API_PREFIX = "/api/v1";
 var OPERATOR_EMAIL_HEADER = "X-Operator-Email";
 function withOperatorAttribution(client, options) {
-  const operatorEmail = isImpersonatedSession(client.session) ? client.session.impersonatorEmail : client.session.cookieless === true && !hasApiKey(client.session) && client.session.interactiveLogin !== true ? void 0 : client.email;
+  const operatorEmail = isImpersonatedSession(client.session) ? client.session.impersonatorEmail : client.session.cookieless === true && !hasApiKey(client.session) && !hasApiKeyEnvVar(client.session) && client.session.interactiveLogin !== true ? void 0 : client.email;
   if (operatorEmail === void 0) return options ?? {};
   return {
     ...options,

package/dist/scopes-map.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "cliVersion": "1.6.96",
+  "cliVersion": "1.6.98",
   "_contract": "Resolve a command path through `aliases` (canonical prefix + alias segment -> canonical path) before any lookup. A path listed in `pendingCommands`, or whose first segment is a key of `pending`, is UNDECIDED, not unrestricted: fail closed or skip it, and never read a path's absence from `commands` as 'no requirement'. An entry carrying `denied` is UNAVAILABLE to any AGENT-SCOPED credential — one whose `scopes` claim carries at least one `resource:action` entry; a claim that is absent, empty, capability-only or wholly unparseable is UNRESTRICTED, and this mark does not apply to it — whatever else that entry says: it is not a ceiling and it is not always-available, its `denied.reason` says why and `denied.until` names the ticket that lifts it, and the absence of `requires` on it must NEVER be read as 'no requirement'. Only an entry in `commands` with an empty `requires` means always-available.",
   "commands": {
     "login": {

package/dist/skills/dr-cli/reference/reconciliation-mec.md

@@ -45,8 +45,8 @@ Account assignment / sign-off (all take the bank-account UUID via
   resets. Every account is checked before anything is written, and the
   write goes out in PATCHes of 100 accounts. If one fails, the error says
   how many accounts landed; re-run the same file without a token and the
-  new plan covers only the rest. Before each PATCH after the first, the
-  accounts are re-read; if any account in the next chunk is gone (a
+  new plan covers only the rest. Before each PATCH, the accounts are
+  re-read; if any account in the next chunk is gone (a
   trial-balance rebuild re-mints account ids) or its member slots changed
   since the plan, the run halts, says how many accounts landed, and names
   the drifted accounts. Gone accounts mean the file must be rebuilt from
@@ -55,6 +55,13 @@ Account assignment / sign-off (all take the bank-account UUID via
 - `reconciliation accounts clear-assignee <account_uuid> --date <YYYY-MM-DD>
   --type Preparer|Reviewer` — unassigns (preserves due_date, resets sign-off).
   Two-step confirm.
+- `reconciliation accounts clear-assignee --file <csv> --date <YYYY-MM-DD>` —
+  the bulk form. Header `account_id,type`, one row per (account, role); the
+  user columns of a set-assignee file are rejected, so a set-assignee
+  manifest cannot be passed here by mistake. One plan and one token cover the
+  whole file. Slots already Unassigned, and accounts with no member slots,
+  are skipped. Same 100-account PATCHes, per-chunk re-check, and resume
+  behaviour as `set-assignee --file`.
 - `reconciliation accounts set-due-date <account_uuid> --date <YYYY-MM-DD>
   --type Preparer|Reviewer (--due-date <YYYY-MM-DD> | --epoch <n> | --clear)`.
   Two-step confirm.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datarails-ai/dr-cli",
-  "version": "1.6.96",
+  "version": "1.6.98",
   "description": "Datarails CLI",
   "type": "module",
   "engines": {
@@ -17,7 +17,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@datarails-ai/dr-appspace-cli": "0.10.20",
+    "@datarails-ai/dr-appspace-cli": "0.10.21",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "^1.3.0",
     "commander": "^12.1.0",