@lambdacurry/arbor 0.24.1 → 0.24.3

package/README.md

@@ -101,6 +101,14 @@ and `attachment list` (`attachment_list`, `list_attachments`) recover receipts;
 pages with `--cursor`. Finalized receipts replay with the same authentic token even after expiry.
 Duplicate SHA-256 warnings on the same Thread are best-effort; concurrent uploads may not warn.
 
+Several files work in one command: `arbor attachment upload a.png b.png --thread-id thr_… --description "A" --description "B"`.
+Repeated `--description` flags pair with files by order (none = filename defaults, otherwise exactly one per
+file; write a value that starts with `--` as `--description=<value>`; values are literal, so a leading `[` is text). A blank description or a path listed twice is an error. The whole batch is checked before the
+first request and uploads one file at a time; a mid-batch failure prints what uploaded, what failed and what
+was not attempted, and exits non-zero. `--dry-run` prints the plan and makes no network call. Every receipt
+carries a `nextStep` (unbound until bound to `contribute`/`respond`, max 10 per contribution; descriptions are
+permanent) and may warn when a description is reused for a different file on the same Thread.
+
 MCP exposes **one** tool, `attachment`, with `upload_url` / `attach` / `get` / `list` verbs.
 Refresh a stale client tool catalog if it still shows the retired individual tools, or use
 `arbor attachment upload`. `thread get --view full` retains body/Attachment read-back.

package/dist/arbor.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@lambdacurry/arbor",
-  version: "0.24.1",
+  version: "0.24.3",
   description: "The Arbor CLI — a shared workspace for people and agents. The human + headless-agent write path over Arbor's guarded operation surface.",
   keywords: [
     "agents",
@@ -5162,6 +5162,7 @@ var ARTIFACT_TYPES = [
 ];
 // ../core/src/blob/attachment-upload.ts
 var MAX_ATTACHMENT_BYTES = 1e8;
+var ATTACHMENT_ATTACH_NEXT_STEP = "Unbound until you pass attachmentIds (max 10 per contribution) to contribute or respond. The description is permanent (it becomes the Artifact summary): to fix it before binding, re-upload and bind only the new id. Paste attachments[].markdown verbatim; don't rebuild it from the description.";
 var AGENT_ATTACHMENT_MIME_TYPES = [
   "image/png",
   "image/jpeg",
@@ -8235,6 +8236,11 @@ var MAX_WAY_LEN = WAYS_TO_HELP_LIMITS.maxItemLength;
 
 // ../core/src/ops/computer-output.ts
 var COMPUTER_OUTPUT_DEFAULT_STALE_MS = 24 * 60 * 60 * 1000;
+var OPERATION_LOSS_REASONS = new Set([
+  "process_provider_lost",
+  "workspace_expired",
+  "run_runtime_lost"
+]);
 
 // ../core/src/ops/computer-run-retention.ts
 var COMPUTER_RUN_RETENTION_WARNING_MS = 24 * 60 * 60 * 1000;
@@ -10328,8 +10334,19 @@ var MCP_OUTPUT_SCHEMAS = {
     uploadedByProfileId: id,
     createdAt: timestamp,
     attachments: array(attachment2),
+    replayed: boolean2().optional(),
+    nextStep: string2().optional(),
     warnings: array(string2()).optional()
   }),
+  attachment_upload: looseObject({
+    attachmentId: id.optional(),
+    attachmentIds: array(id),
+    attachments: array(attachment2),
+    nextStep: string2().optional(),
+    warnings: array(string2()).optional(),
+    failed: array(looseObject({ file: string2(), error: string2() })).optional(),
+    notAttempted: array(string2()).optional()
+  }),
   computer_export: looseObject({
     computerSessionId: id,
     replayed: boolean2(),
@@ -10421,8 +10438,6 @@ var MCP_OUTPUT_SCHEMAS = {
   })
 };
 function outputSchemaFor(actionName) {
-  if (actionName === "attachment_upload")
-    actionName = "attachment_attach";
   return MCP_OUTPUT_SCHEMAS[actionName];
 }
 
@@ -11287,6 +11302,17 @@ function proseList(description) {
 function isProseList(schema) {
   return PROSE_LISTS.has(schema);
 }
+var VERBATIM_LISTS = registry();
+function verbatimList(description) {
+  const schema = array(string2()).describe(description);
+  PROSE_LISTS.add(schema, { literal: true });
+  VERBATIM_LISTS.add(schema, { verbatim: true });
+  return schema;
+}
+function isVerbatimList(schema) {
+  return VERBATIM_LISTS.has(schema);
+}
+var ATTACHMENT_DESCRIPTION_HINT = "durable summary and default alt text; defaults to the filename when omitted; permanent once bound; 1-500 chars; give each file its own";
 function forward(operation) {
   const run = (ex, input) => ex.call(operation, input);
   run.operation = operation;
@@ -12314,14 +12340,14 @@ var ACTION_DEFINITIONS = [
   {
     name: "attachment",
     title: "Upload and read Thread Attachments",
-    description: "Upload a file (100 MB cap): upload_url → signed PUT (5 min) → attach (1 h after PUT expiry); receipts replay after expiry; JSON syntax checks stop at 10 MB, larger JSON gets UTF-8/control checks only, so validate locally. get/list recover receipts; mediaUrl/downloadUrl require an Arbor credential (401 otherwise), with no public read URLs.",
+    description: "Upload (100 MB): upload_url → signed PUT (5 min) → attach (1 h after PUT expiry); receipts replay after expiry; JSON syntax checked ≤10 MB, larger JSON gets UTF-8/control checks only (validate locally); get/list recover receipts; read URLs need Arbor credentials (401 otherwise), no public URLs. Missing tool: refresh the MCP tool catalog; CLI: arbor attachment upload (Node/Bun).",
     inputSchema: {
       verb: _enum(["upload_url", "attach", "get", "list"]),
       threadId: string2().optional().describe("upload_url/list: Thread id, thr_…"),
       filename: string2().min(1).max(1000).optional().describe("upload_url: original filename"),
       mimeType: _enum(AGENT_ATTACHMENT_MIME_TYPES).optional().describe("upload_url: supported MIME matching the bytes"),
       size: number2().optional().describe("upload_url: exact file size, at most 100000000 bytes; compress, split, or link larger files"),
-      description: string2().min(1).max(500).optional(),
+      description: string2().min(1).max(500).optional().describe(`upload_url: ${ATTACHMENT_DESCRIPTION_HINT}`),
       sha256: string2().regex(/^[a-f0-9]{64}$/).optional().describe("upload_url: optional SHA-256 hex; also signed into the PUT checksum header"),
       token: string2().optional().describe("attach: token from upload_url; first attach before attachExpiresAt, replay finalized receipts even after expiry"),
       attachmentId: string2().optional().describe("get: attachment id, att_…"),
@@ -12345,7 +12371,7 @@ var ACTION_DEFINITIONS = [
       filename: string2().min(1).max(1000),
       mimeType: _enum(AGENT_ATTACHMENT_MIME_TYPES),
       size: number2(),
-      description: string2().min(1).max(500).optional(),
+      description: string2().min(1).max(500).optional().describe(ATTACHMENT_DESCRIPTION_HINT),
       sha256: string2().regex(/^[a-f0-9]{64}$/).optional()
     },
     surfaces: ["cli"],
@@ -12381,12 +12407,25 @@ var ACTION_DEFINITIONS = [
   },
   {
     name: "attachment_upload",
-    title: "Upload a local Thread file",
-    description: "Upload with Node and SHA-256 via upload_url → presigned PUT → attach (100 MB cap); compress, split, or link larger files; JSON syntax checks stop at 10 MB, larger JSON gets UTF-8/control checks only. PUT expires in 5 min, first attach gets 1 h more, receipts replay after expiry; js-exec cannot upload; mediaUrl/downloadUrl require an Arbor credential (401 otherwise), no public read URLs; for a missing tool refresh the MCP tool catalog or use arbor attachment upload.",
+    title: "Upload local Thread files",
+    description: "Upload local files with Node or Bun (SHA-256 → presigned PUT → attach, 100 MB cap)",
+    cliHelpLead: "Requires Node or Bun.",
+    cliHelpNotes: [
+      "Upload with SHA-256 via upload_url → presigned PUT → attach (100 MB cap); compress, split, or link larger files.",
+      'Several files: `arbor attachment upload a.png b.png --thread-id thr_… --description "A" --description "B"`. Repeated --description flags pair with the files by ORDER: pass none (each defaults to its filename) or exactly one per file; a value that starts with `--` must be written --description=<value>. The whole batch is checked before the first request, then uploaded one by one; if one fails the output lists what uploaded and what failed (exit non-zero). --dry-run prints the plan and makes no network call.',
+      `Description: ${ATTACHMENT_DESCRIPTION_HINT}. An upload is unbound until you pass its attachmentIds to contribute or respond (max 10 per contribution); to fix a description before binding, re-upload and bind only the new id. Paste attachments[].markdown verbatim; don't rebuild it from the description.`,
+      "PUT links expire after five minutes; first attach is allowed until one hour after PUT expiry. Finalized receipts replay after expiry.",
+      "JSON syntax checks stop at 10 MB; larger JSON gets UTF-8/control checks only, so validate syntax locally.",
+      "js-exec lacks file descriptors, node:crypto, and binary-safe fetch; run this command with Node or Bun.",
+      "With only curl available, use the MCP attachment tool: upload_url → returned curl PUT command → attach with the returned token.",
+      "mediaUrl/downloadUrl require an Arbor credential (401 otherwise); no public read URLs. The R2 PUT uses only the required signed headers, never an Arbor credential."
+    ].join(`
+`),
     inputSchema: {
       threadId: string2().min(1),
-      file: string2().min(1).describe("local file path (or positional file); requires Node"),
-      description: string2().min(1).max(500).optional()
+      file: verbatimList("local file path(s), or positional files; uploaded in order; requires Node or Bun"),
+      description: verbatimList(`${ATTACHMENT_DESCRIPTION_HINT}; repeat --description once per file, paired by order (none = filenames)`).optional(),
+      dryRun: boolean2().optional().describe("print the upload plan (file, mime, size, sha256, description) with no network call")
     },
     surfaces: ["cli"],
     toolset: "loop",
@@ -14667,6 +14706,19 @@ class UsageError extends Error {
   }
 }
 
+class PartialUploadError extends Error {
+  partialResult;
+  code;
+  details;
+  constructor(message, cause, partialResult) {
+    super(message);
+    this.partialResult = partialResult;
+    this.name = "PartialUploadError";
+    this.code = codeForError(cause);
+    this.details = detailsForError(cause);
+  }
+}
+
 // src/config.ts
 var PROD_API_URL = "https://arborthreads.com";
 var PROFILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
@@ -15041,7 +15093,7 @@ var httpExecutor = {
 };
 
 // src/attachment-upload.ts
-import { basename } from "node:path";
+import { basename, resolve } from "node:path";
 function checkFile(stat) {
   const isFile = typeof stat.isFile === "function" ? stat.isFile() : stat.isFile;
   if (!isFile)
@@ -15051,8 +15103,7 @@ function checkFile(stat) {
   if (!stat.size)
     throw new UsageError("Attachment file is empty (0 bytes); choose a non-empty file");
 }
-async function uploadLocalAttachment(executor, input, fetcher = fetch) {
-  const file = String(input.file);
+async function preflightFile(file) {
   const filename = basename(file);
   const fs = await import("node:fs");
   const initialStat = fs.statSync(file);
@@ -15060,8 +15111,11 @@ async function uploadLocalAttachment(executor, input, fetcher = fetch) {
   const mimeType = localAttachmentMime(filename);
   if (!mimeType)
     throw new UsageError(`Unsupported file extension for ${initialStat.size} bytes (limit ${MAX_ATTACHMENT_BYTES} bytes). Use PNG/JPEG/GIF/WebP/PDF/TXT/JSON/CSV, or link the file.`);
-  if (typeof fs.openSync !== "function")
-    throw new UsageError("Attachment upload requires Node: this js-exec runtime cannot PUT binary file bytes. Run `arbor attachment upload <file> --thread-id <thread>` with Node.");
+  if ([fs.openSync, fs.fstatSync, fs.readSync, fs.closeSync].some((api) => typeof api !== "function"))
+    throw new UsageError("Attachment upload requires Node or Bun: js-exec lacks file descriptors, node:crypto, and binary-safe fetch. Run `arbor attachment upload <file> --thread-id <thread>` with Node or Bun, or use MCP attachment upload_url → curl PUT → attach.");
+  return { fs, local: { file, filename, mimeType, size: initialStat.size } };
+}
+async function putLocalAttachment(executor, fs, { file, filename, mimeType }, input, fetcher) {
   const descriptor = fs.openSync(file, "r");
   let bytes;
   try {
@@ -15107,6 +15161,135 @@ async function uploadLocalAttachment(executor, input, fetcher = fetch) {
     throw new ApiError(`Attachment PUT failed (${response.status}) for ${bytes.length} bytes (limit ${MAX_ATTACHMENT_BYTES} bytes). Request a fresh upload_url if expired, then retry; compress, split, or link files above the limit.`, response.status);
   return executor.call("attachment.attach", { token: link.token });
 }
+function normalizeDescription(value) {
+  return value.trim().replace(/\s+/g, " ");
+}
+function asList(value) {
+  if (value === undefined)
+    return [];
+  return (Array.isArray(value) ? value : [value]).map(String);
+}
+async function planBatch(input) {
+  const files = asList(input.file);
+  const descriptions = asList(input.description);
+  if (files.length === 0)
+    throw new UsageError("missing required flag: --file");
+  if (descriptions.length > 0 && descriptions.length !== files.length) {
+    throw new UsageError(files.length > 1 && descriptions.length === 1 ? `One --description for ${files.length} files would give every file the same permanent description. Pass one --description per file in file order, or none to default each to its filename.` : `Got ${descriptions.length} --description flag${descriptions.length === 1 ? "" : "s"} for ${files.length} file${files.length === 1 ? "" : "s"}; descriptions pair with files by order, so pass none or exactly one per file.`, { reason: "validation.invalid_value", field: "description" });
+  }
+  for (const description of descriptions) {
+    const length = normalizeDescription(description).length;
+    if (length < 1)
+      throw new UsageError("--description is blank; give each file a real description, or omit --description to default it to the filename", { reason: "validation.invalid_value", field: "description" });
+    if (length > 500)
+      throw new UsageError("--description must be 1–500 characters", {
+        reason: "validation.invalid_value",
+        field: "description"
+      });
+  }
+  const paths = new Map;
+  for (const file of files) {
+    if (!file.trim())
+      throw new UsageError("--file is blank; pass a path to a local file");
+    const key = resolve(file);
+    const first = paths.get(key);
+    if (first !== undefined)
+      throw new UsageError(`${file} is listed twice${first === file ? "" : ` (as ${first})`}; each file uploads once, so list it once.`, { reason: "validation.invalid_value", field: "file" });
+    paths.set(key, file);
+  }
+  let fs;
+  const plan = [];
+  for (const [index, file] of files.entries()) {
+    const prepared = await preflightFile(file);
+    fs = prepared.fs;
+    plan.push({ local: prepared.local, description: descriptions[index] });
+  }
+  const seen = new Map;
+  for (const { local, description } of plan) {
+    if (description === undefined)
+      continue;
+    const key = normalizeDescription(description);
+    const first = seen.get(key);
+    if (first !== undefined)
+      throw new UsageError(`Duplicate --description "${key}" for ${first} and ${local.file}; descriptions are permanent, so give each file its own.`, { reason: "validation.invalid_value", field: "description" });
+    seen.set(key, local.file);
+  }
+  return { fs, plan };
+}
+function sha256File(fs, file, createHash) {
+  const hash = createHash("sha256");
+  const chunk = Buffer.alloc(1048576);
+  const descriptor = fs.openSync(file, "r");
+  try {
+    for (;; ) {
+      const count = fs.readSync(descriptor, chunk, 0, chunk.length, null);
+      if (!count)
+        break;
+      hash.update(chunk.subarray(0, count));
+    }
+  } finally {
+    fs.closeSync(descriptor);
+  }
+  return hash.digest("hex");
+}
+async function dryRunPlan(fs, threadId, plan) {
+  const { createHash } = await import("node:crypto");
+  return {
+    dryRun: true,
+    threadId,
+    files: plan.map(({ local, description }) => ({
+      file: local.file,
+      filename: local.filename,
+      mimeType: local.mimeType,
+      size: local.size,
+      sha256: sha256File(fs, local.file, createHash),
+      description: description ?? local.filename,
+      descriptionSource: description === undefined ? "filename default" : "explicit",
+      status: "unbound until attached"
+    }))
+  };
+}
+function record3(value) {
+  return value !== null && typeof value === "object" ? value : {};
+}
+function aggregateReceipt(uploaded, extra = {}) {
+  const warnings = uploaded.flatMap(({ local, receipt }) => asList(record3(receipt).warnings).map((warning) => `${local.filename}: ${warning}`));
+  return {
+    attachmentIds: uploaded.flatMap(({ receipt }) => {
+      const r = record3(receipt);
+      return Array.isArray(r.attachmentIds) ? r.attachmentIds : typeof r.attachmentId === "string" ? [r.attachmentId] : [];
+    }),
+    attachments: uploaded.flatMap(({ receipt }) => {
+      const attachments = record3(receipt).attachments;
+      return Array.isArray(attachments) ? attachments : [];
+    }),
+    nextStep: ATTACHMENT_ATTACH_NEXT_STEP,
+    ...warnings.length > 0 ? { warnings } : {},
+    ...extra
+  };
+}
+async function uploadLocalAttachments(executor, input, fetcher = fetch) {
+  const { fs, plan } = await planBatch(input);
+  if (input.dryRun === true)
+    return dryRunPlan(fs, String(input.threadId), plan);
+  const upload = ({ local, description }) => putLocalAttachment(executor, fs, local, { threadId: input.threadId, ...description !== undefined ? { description } : {} }, fetcher);
+  if (plan.length === 1)
+    return upload(plan[0]);
+  const uploaded = [];
+  for (const [index, item] of plan.entries()) {
+    try {
+      uploaded.push({ local: item.local, receipt: await upload(item) });
+    } catch (cause) {
+      const reason = cause instanceof Error ? cause.message : String(cause);
+      const notAttempted = plan.slice(index + 1).map(({ local }) => local.file);
+      throw new PartialUploadError(`Uploaded ${uploaded.length} of ${plan.length} files; ${item.local.file} failed: ${reason.replace(/\.$/, "")}. Uploaded files stay valid but unbound; re-run only the failed and not-attempted files.`, cause, aggregateReceipt(uploaded, {
+        failed: [{ file: item.local.file, error: reason }],
+        notAttempted
+      }));
+    }
+  }
+  return aggregateReceipt(uploaded);
+}
 
 // src/output.ts
 function writeOutput(value, stream, fallback) {
@@ -15198,15 +15381,20 @@ function emitData(data, _action, ctx) {
 function emitError(err, _action, ctx) {
   const code = codeForError(err);
   const message = err instanceof Error ? err.message : String(err);
+  const partial = err instanceof PartialUploadError ? err.partialResult : undefined;
   if (ctx.json) {
     const envelope = {
       ok: false,
-      error: { code, message, ...detailsForError(err) }
+      error: { code, message, ...detailsForError(err) },
+      ...partial !== undefined ? { data: partial } : {}
     };
     writeStdout(`${JSON.stringify(envelope)}
 `);
     process.exitCode = exitCodeForError(code);
   } else {
+    if (partial !== undefined)
+      writeStdout(`${JSON.stringify(partial, null, 2)}
+`);
     writeStderr(`✗ ${message}
 `);
     process.exitCode = 1;
@@ -15228,7 +15416,7 @@ var DEFAULT_PROCESS_DEADLINE_MS = 1800000;
 var PROCESS_OUTPUT_PAGE_BYTES = 4096;
 var POLL_MS = 400;
 var processRead = ACTIONS3.find((action) => action.name === "computer_process_read");
-function record3(value) {
+function record4(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
 function isRunning(value) {
@@ -15256,7 +15444,7 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function isComputerExecHandle(value) {
-  const rec = record3(value);
+  const rec = record4(value);
   return Boolean(rec && typeof rec.processId === "string" && (isRunning(rec) || rec.truncated === true));
 }
 async function waitForComputerExec(executor, input, value, ctx) {
@@ -15271,7 +15459,7 @@ async function waitForComputerExec(executor, input, value, ctx) {
 `, ctx);
   while (isRunning(latest) && Date.now() < deadline) {
     await sleep(POLL_MS);
-    const read = record3(await processRead.run(executor, {
+    const read = record4(await processRead.run(executor, {
       processId: latest.processId,
       maxBytes: PROCESS_OUTPUT_PAGE_BYTES,
       ...cursor ? { cursor } : {},
@@ -15345,6 +15533,7 @@ function kindOf(node) {
       return "string";
   }
 }
+var BARE_VALUE_HINT = (flag) => ` (a value that starts with "--" must be written --${flag}=<value>)`;
 function acceptedFlags(inputSchema) {
   const out = new Set;
   for (const spec of flagsForSchema(inputSchema)) {
@@ -15377,7 +15566,8 @@ function flagsForSchema(inputSchema) {
       required: !optional,
       nullable,
       description: description(inner) ?? description(raw),
-      literal: isProseList(inner)
+      literal: isProseList(inner),
+      verbatim: isVerbatimList(inner)
     };
   });
 }
@@ -15418,7 +15608,7 @@ function buildInput(inputSchema, flags, command) {
       continue;
     }
     if (spec.kind !== "boolean" && raw === true) {
-      throw new UsageError(`--${spec.flag} expects a value`, {
+      throw new UsageError(`--${spec.flag} expects a value${BARE_VALUE_HINT(spec.flag)}`, {
         reason: "validation.missing_field",
         field: spec.field
       });
@@ -15441,6 +15631,10 @@ function buildInput(inputSchema, flags, command) {
       case "array": {
         const repeated = Array.isArray(raw);
         const tokens = repeated ? raw : [String(raw)];
+        if (spec.verbatim) {
+          input[spec.field] = tokens.map(String);
+          break;
+        }
         const out = [];
         for (const token of tokens) {
           const text = String(token).trim();
@@ -15696,6 +15890,7 @@ var POSITIONAL_FIELDS = {
   code_implementations: ["namePath", "path"],
   code_diagnostics: ["path"]
 };
+var VARIADIC_LAST_POSITIONAL = new Set(["attachment_upload"]);
 function positionalSpecs(action) {
   const fields = POSITIONAL_FIELDS[action.name];
   if (!fields)
@@ -15783,7 +15978,11 @@ function toolNameAliases(action) {
 function helpLine(action) {
   const positionals = positionalSpecs(action);
   const positionalFlags = new Set(positionals.map((spec) => spec.flag));
-  const args = positionals.map((spec) => spec.required ? ` <${spec.field}>` : ` [<${spec.field}>]`).join("");
+  const args = positionals.map((spec, index) => {
+    const variadic = VARIADIC_LAST_POSITIONAL.has(action.name) && index === positionals.length - 1;
+    const name = `${spec.field}${variadic ? ">..." : ">"}`;
+    return spec.required ? ` <${name}` : ` [<${name}]`;
+  }).join("");
   const flags = flagsForSchema(action.inputSchema).filter((spec) => !positionalFlags.has(spec.flag)).map((f) => {
     const token = f.kind === "boolean" ? `--${f.flag}` : `--${f.flag} <>`;
     return f.required ? token : `[${token}]`;
@@ -15809,7 +16008,11 @@ function commandHelp(positionals) {
     const token = f.kind === "boolean" ? `--${f.flag}` : `--${f.flag} <${f.kind}>`;
     return f.required ? token : `[${token}]`;
   }).join(" ");
-  const usageArgs = helpPositionals.map((spec) => spec.required ? ` <${spec.field}>` : ` [<${spec.field}>]`).join("");
+  const usageArgs = helpPositionals.map((spec, index) => {
+    const variadic = VARIADIC_LAST_POSITIONAL.has(action.name) && index === helpPositionals.length - 1;
+    const name = `${spec.field}${variadic ? ">..." : ">"}`;
+    return spec.required ? ` <${name}` : ` [<${name}]`;
+  }).join("");
   const usage = `Usage: arbor ${commandWords(action)}${usageArgs}${usageFlags ? ` ${usageFlags}` : ""}`;
   const lines = specs.map((f) => {
     const positional = helpPositionals.find((spec) => spec.flag === f.flag);
@@ -15838,12 +16041,24 @@ Aliases: ${aliases.map((alias) => `\`arbor ${alias}\``).join(", ")} (tool-name f
   const waitLines = action.name === "computer_exec" ? [
     "  --no-wait [<boolean>]  [optional] — return a running processId immediately instead of polling computer_process_read (implied by --background); mutually exclusive with --wait-for-terminal-ms"
   ] : [];
+  const notes = action.cliHelpNotes ? `
+
+${action.cliHelpNotes}` : "";
+  if (action.cliHelpLead) {
+    return `${usage}
+
+${action.cliHelpLead}
+
+${lines.join(`
+`)}${primaryNote}${explicitNote}${aliasNote}${notes}
+`;
+  }
   return `${heading} — ${action.description}
 
 ${usage}${waitLines.length > 0 ? " [--no-wait]" : ""}
 
 ${[...lines, ...waitLines].join(`
-`)}${primaryNote}${explicitNote}${aliasNote}
+`)}${primaryNote}${explicitNote}${aliasNote}${notes}
 `;
 }
 function commandCatalog() {
@@ -15879,10 +16094,12 @@ function applyPositionals(action, extras, flags) {
   if (positionalTargets.length === 0) {
     throw new UsageError(`unexpected argument: ${extras[0]} (\`${commandWords(action)}\` takes no positional — use flags)`);
   }
-  if (extras.length > positionalTargets.length) {
+  const fixed = positionalTargets.length - 1;
+  const values = VARIADIC_LAST_POSITIONAL.has(action.name) && extras.length > fixed ? [...extras.slice(0, fixed), extras.slice(fixed)] : extras;
+  if (values.length > positionalTargets.length) {
     throw new UsageError(`too many arguments: \`${commandWords(action)}\` takes ${positionalTargets.length === 1 ? "one positional" : `${positionalTargets.length} positionals`}; pass the rest as flags`);
   }
-  for (const [index, value] of extras.entries()) {
+  for (const [index, value] of values.entries()) {
     const target = positionalTargets[index];
     if (flags[target.flag] !== undefined || flags[`${target.flag}-file`] !== undefined) {
       throw new UsageError(`pass --${target.flag} either as a flag or as the positional argument, not both`);
@@ -15920,8 +16137,16 @@ async function runObjectVerb(positionals, flags, ctx) {
   const unknown = Object.keys(flags).filter((f) => !accepted.has(f) && !RESERVED_FLAGS.has(f));
   if (unknown.length > 0) {
     const hints = unknown.map((f) => listFileHint(action, f)).filter(Boolean);
+    const bare = flagsForSchema(action.inputSchema).find((spec) => spec.kind !== "boolean" && flags[spec.flag] === true);
+    if (bare)
+      hints.push(`--${bare.flag} has no value${BARE_VALUE_HINT(bare.flag)}`);
     throw new UsageError(`unknown flag${unknown.length > 1 ? "s" : ""}: ${unknown.map((f) => `--${f}`).join(", ")}${hints.length > 0 ? ` — ${hints.join("; ")}` : ""}`);
   }
+  if (action.name === "attachment_upload") {
+    const dryRun = lastValue(flags["dry-run"]);
+    if (typeof dryRun === "string" && dryRun !== "true" && dryRun !== "false")
+      throw new UsageError(`--dry-run takes no value but swallowed "${dryRun}"; put --dry-run after the files or write --dry-run=true`, { reason: "validation.invalid_value", field: "dryRun" });
+  }
   const inputFlags = { ...flags };
   if (action.name === "app_request" && lastValue(inputFlags.json) === true) {
     delete inputFlags.json;
@@ -15958,7 +16183,7 @@ async function runObjectVerb(positionals, flags, ctx) {
     advise(`Agent registered. Save its apiKey now — it is shown only once:
 `, ctx);
   }
-  let value = action.name === "attachment_upload" ? await uploadLocalAttachment(httpExecutor, input) : await action.run(httpExecutor, input);
+  let value = action.name === "attachment_upload" ? await uploadLocalAttachments(httpExecutor, input) : await action.run(httpExecutor, input);
   if (action.name === "computer_exec" && !truthyFlag(flags["no-wait"]) && input.waitForTerminalMs === undefined && input.background !== true) {
     value = await waitForComputerExec(httpExecutor, input, value, ctx);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lambdacurry/arbor",
-  "version": "0.24.1",
+  "version": "0.24.3",
   "description": "The Arbor CLI — a shared workspace for people and agents. The human + headless-agent write path over Arbor's guarded operation surface.",
   "keywords": [
     "agents",