@lambdacurry/arbor 0.24.2 → 0.24.4

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.2",
+  version: "0.24.4",
   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",
@@ -29,7 +29,7 @@ var package_default = {
     access: "public"
   },
   scripts: {
-    arbor: "tsx src/bin.ts",
+    arbor: "vpx src/bin.ts",
     build: "bun build ./src/bin.ts --target=node --outfile=dist/arbor.js",
     test: "vp test run --passWithNoTests",
     typecheck: "tsc -b",
@@ -40,7 +40,6 @@ var package_default = {
     "@arbor/core": "workspace:*",
     "@types/node": "^26.2.0",
     "just-bash": "3.4.2",
-    tsx: "^4.20.6",
     typescript: "^5.8.0",
     "vite-plus": "catalog:",
     zod: "^4.4.3"
@@ -5162,6 +5161,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",
@@ -6579,10 +6579,20 @@ var spaces = sqliteTable("spaces", {
   defaultReviewDimensions: text("default_review_dimensions", { mode: "json" }).$type().notNull().default([]),
   stage: text("stage").$type().notNull().default("exploration"),
   systemKind: text("system_kind"),
+  key: text("key"),
   createdAt: ts("created_at").notNull()
 }, (t) => ({
   orgIdx: index("spaces_org_idx").on(t.orgId),
-  systemKindUq: uniqueIndex("spaces_system_kind_uq").on(t.systemKind)
+  systemKindUq: uniqueIndex("spaces_system_kind_uq").on(t.systemKind),
+  orgKeyUq: uniqueIndex("spaces_org_key_uq").on(t.orgId, t.key)
+}));
+var spaceRetiredKeys = sqliteTable("space_retired_keys", {
+  orgId: text("org_id").notNull().references(() => orgs.id),
+  key: text("key").notNull(),
+  spaceId: text("space_id").notNull().references(() => spaces.id),
+  retiredAt: ts("retired_at").notNull()
+}, (t) => ({
+  orgKeyUq: uniqueIndex("space_retired_keys_org_key_uq").on(t.orgId, t.key)
 }));
 var spaceMemberships = sqliteTable("space_memberships", {
   id: text("id").primaryKey(),
@@ -6712,8 +6722,10 @@ var threads = sqliteTable("threads", {
   waysToHelp: text("ways_to_help", { mode: "json" }).$type().notNull().default([]),
   openQuestions: text("open_questions", { mode: "json" }).$type().notNull().default([]),
   expectedOutput: text("expected_output").notNull().default(""),
+  number: integer2("number"),
   createdAt: ts("created_at").notNull()
 }, (t) => ({
+  spaceNumberUq: uniqueIndex("threads_space_number_uq").on(t.spaceId, t.number),
   topicIdx: index("threads_topic_idx").on(t.topicId),
   spaceIdx: index("threads_space_idx").on(t.spaceId),
   lifecycleTypeIdx: index("threads_lifecycle_type_idx").on(t.lifecycleType),
@@ -8217,6 +8229,36 @@ var ORG_ADMIN_CONTAINMENT_PERMISSIONS = new Set([
   "revoke"
 ]);
 
+// ../core/src/queries/artifact-base.ts
+var eventChronology = sql`_rowid_`;
+var SPACE_ARTIFACT_STATUSES = [
+  "draft",
+  "proposed",
+  "active",
+  "promoted",
+  "needs-review",
+  "superseded",
+  "deprecated",
+  "archived"
+];
+var artifactUpdatedAt = sql`coalesce((select max(${events.createdAt}) from ${events} where ${events.objectType} = 'artifact' and ${events.objectId} = ${artifacts.id}), ${artifacts.createdAt})`;
+// ../core/src/queries/thread-assignment.ts
+var assigneeColumns = {
+  threadId: threadAssignments.threadId,
+  assignedAt: threadAssignments.createdAt,
+  assignedByProfileId: threadAssignments.assignedByProfileId,
+  id: profiles.id,
+  kind: profiles.kind,
+  displayName: profiles.displayName,
+  color: profiles.color,
+  emoji: profiles.emoji
+};
+var lastActivityExpr = sql`coalesce(
+  (select max(${contributions.createdAt}) from ${contributions}
+    where ${contributions.threadId} = ${threads.id}),
+  ${threads.createdAt}
+)`;
+
 // ../core/src/ops/space.ts
 var GUIDANCE_LIMITS = {
   maxItems: 12,
@@ -8235,6 +8277,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;
@@ -8284,20 +8331,6 @@ var COMPUTER_WORKSPACE_RECOVERY_ATTACH_DEADLINE_MS = 31 * 60 * 1000;
 var COMPUTER_WORKSPACE_RECOVERY_HEALTH_DEADLINE_MS = 2 * 60 * 1000;
 var COMPUTER_WORKSPACE_RECOVERY_HEADROOM_MS = 2 * 60 * 1000;
 var COMPUTER_WORKSPACE_RECOVERY_LEASE_MS = COMPUTER_WORKSPACE_RECOVERY_CHECKPOINT_DEADLINE_MS + COMPUTER_WORKSPACE_RECOVERY_ATTACH_DEADLINE_MS + COMPUTER_WORKSPACE_RECOVERY_HEALTH_DEADLINE_MS + COMPUTER_WORKSPACE_RECOVERY_HEADROOM_MS;
-
-// ../core/src/queries/artifact-base.ts
-var eventChronology = sql`_rowid_`;
-var SPACE_ARTIFACT_STATUSES = [
-  "draft",
-  "proposed",
-  "active",
-  "promoted",
-  "needs-review",
-  "superseded",
-  "deprecated",
-  "archived"
-];
-var artifactUpdatedAt = sql`coalesce((select max(${events.createdAt}) from ${events} where ${events.objectType} = 'artifact' and ${events.objectId} = ${artifacts.id}), ${artifacts.createdAt})`;
 // ../core/src/ops/artifact-git-intent.ts
 var RETRYABLE_REPAIR = new Set([
   "pending_push_unconfirmed",
@@ -8315,22 +8348,6 @@ var EMOJI_RE = new RegExp("^\\p{RGI_Emoji}$", "v");
 var BASE_MS = Date.parse("2026-07-20T15:00:00.000Z");
 // ../core/src/ops/agent-pairing.ts
 var PAIRING_TTL_MS = 15 * 60 * 1000;
-// ../core/src/queries/thread-assignment.ts
-var assigneeColumns = {
-  threadId: threadAssignments.threadId,
-  assignedAt: threadAssignments.createdAt,
-  assignedByProfileId: threadAssignments.assignedByProfileId,
-  id: profiles.id,
-  kind: profiles.kind,
-  displayName: profiles.displayName,
-  color: profiles.color,
-  emoji: profiles.emoji
-};
-var lastActivityExpr = sql`coalesce(
-  (select max(${contributions.createdAt}) from ${contributions}
-    where ${contributions.threadId} = ${threads.id}),
-  ${threads.createdAt}
-)`;
 // ../core/src/ops/package-cache.ts
 var PACKAGE_CACHE_PENDING_TTL_MS = 15 * 60 * 1000;
 var PACKAGE_CACHE_FINAL_TTL_MS = 30 * 24 * 60 * 60 * 1000;
@@ -8504,6 +8521,7 @@ var recallHit = looseObject({
   excerpt: string2(),
   space: spaceRef.nullable(),
   threadId: nullableString,
+  shortId: nullableString.optional(),
   url: nullableString,
   createdAt: timestamp
 });
@@ -8989,6 +9007,7 @@ var orgMember = looseObject({
 });
 var thread3 = looseObject({
   id,
+  shortId: nullableString.optional(),
   title: string2(),
   objective: string2(),
   status: string2().optional(),
@@ -9027,6 +9046,7 @@ var topic2 = looseObject({
 var space3 = looseObject({
   id,
   title: string2(),
+  key: nullableString.optional(),
   purpose: nullableString.optional(),
   stage: string2().optional(),
   url: string2().optional()
@@ -10328,8 +10348,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 +10452,6 @@ var MCP_OUTPUT_SCHEMAS = {
   })
 };
 function outputSchemaFor(actionName) {
-  if (actionName === "attachment_upload")
-    actionName = "attachment_attach";
   return MCP_OUTPUT_SCHEMAS[actionName];
 }
 
@@ -11146,6 +11175,7 @@ var TLDRAW_EXEC_OPERATIONS_SCHEMA = array(TLDRAW_EXEC_OPERATION_SCHEMA).min(1).m
 // ../actions/src/index.ts
 var ARTIFACT_TYPE_DESCRIPTION = `semantic type (one of: ${ARTIFACT_TYPES.join(", ")})`;
 var ARBOR_FEEDBACK_INPUT_TYPES = [...ARBOR_FEEDBACK_TYPES, "friction"];
+var SPACE_KEY_INPUT = string2().min(1).refine((key) => key.trim().length > 0, "space key cannot be blank");
 var CONTRIBUTION_ADD_LINK_RELS = [
   "cites",
   "contests",
@@ -11287,6 +11317,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;
@@ -11721,7 +11762,7 @@ var ACTION_DEFINITIONS = [
     title: "Contribute to a thread",
     description: "Add one additive point to a Thread; use stamp for agreement, respond/mark_as_response for requests, and links for deliberate reply/contest edges. Pass idempotencyKey (CLI: --idempotency-key) for safe retries.",
     inputSchema: {
-      threadId: string2().describe("the thread id, e.g. thr_…"),
+      threadId: string2().describe("the thread id, e.g. thr_…, or its short id, e.g. BUD-34"),
       type: _enum(CONTRIBUTION_TYPES).describe("the contribution type (AD-066 taxonomy)"),
       body: string2().min(1).describe(`the contribution markdown. ${CONTRIBUTION_BODY_GUIDANCE}`),
       idempotencyKey: string2().min(1).max(200).optional().describe("stable key for this ONE logical contribution (≤200 chars), e.g. cron-run/work-item + output slot; safe retries return the original contribution. Reusing it with different content is a conflict."),
@@ -11880,7 +11921,7 @@ var ACTION_DEFINITIONS = [
     title: "Edit a thread's title, objective, or topic",
     description: "Correct a Thread's title or objective, or move it under another Topic of the same Space, patching only supplied fields; use it to make done clear or refile misfiled work instead of archiving and reopening. Status moves stay with `transition_thread`, column order with `--rank`, and the temporary help list with `charter` ways_to_help.",
     inputSchema: {
-      threadId: string2().describe("the thread to edit, thr_…"),
+      threadId: string2().describe("the thread to edit, thr_… or a short id like BUD-34"),
       title: string2().min(1).optional().describe("a new title — the question, outcome, investigation, instance, or standing concern"),
       objective: string2().min(1).optional().describe("a new objective — what this Thread should accomplish; for finite work, what done means"),
       topicId: string2().optional().describe("move the thread under this topic of the same space, top_…"),
@@ -11896,7 +11937,7 @@ var ACTION_DEFINITIONS = [
     description: "Make a Space member (yourself when profileId is omitted) responsible for moving a Thread, or remove that responsibility; assignment is immediate, idempotent, grants no permissions, and creates no Inbox item — a specific owed action is still a `request`. Assignees stay attached through every lifecycle move, so transfer responsibility by assigning the new owner and unassigning the old.",
     inputSchema: {
       verb: _enum(["assign", "unassign"]).describe("add or remove responsibility"),
-      threadId: string2().describe("the thread, thr_…"),
+      threadId: string2().describe("the thread, thr_… or a short id like BUD-34"),
       profileId: string2().optional().describe("the member to (un)assign, prof_…; omit for yourself")
     },
     surfaces: ["mcp", "cli"],
@@ -11997,7 +12038,7 @@ var ACTION_DEFINITIONS = [
     title: "Replace a Thread computer override",
     description: "DESTRUCTIVE REPLACE: Replace this Thread's entire sparse Computer override; omitted fields are cleared from the Thread layer and inherit Topic/Space/organization policy. This is config only and allocates no runtime; an existing Computer cannot switch provider, and repeating the same full layer is idempotent.",
     inputSchema: {
-      threadId: string2().describe("the Thread, thr_…"),
+      threadId: string2().describe("the Thread, thr_… or a short id like BUD-34"),
       backend: _enum(["worker-shell", "container"]).nullable().optional().describe("override execution tier, or null to inherit"),
       containerProfile: string2().nullable().optional().describe("logical container profile; bun-typescript-v1 guarantees Bash, Git, GitHub CLI (gh), Bun 1.4.2, bunx, Node 26.5.1, pnpm 10.33.0, Python 3.13.15 (python/python3), jq, and ripgrep (rg), or null to clear inherited profile"),
       setupScript: string2().nullable().optional().describe("optional strict Bash setup for a fresh base after repositories materialize; install scoped tools in /workspace/.local/bin so exec finds them and snapshots retain them"),
@@ -12013,7 +12054,7 @@ var ACTION_DEFINITIONS = [
     title: "Attach a Thread computer",
     description: "Deprecated by AD-306: computer_run_start(threadId) attaches durable identity itself, so use this only to mint protocol identity with no Run at all. Creates or reuses the Thread's stable Computer identity and an immutable collaborator receipt without starting provider runtime.",
     inputSchema: {
-      threadId: string2().describe("the Thread whose computer you are attaching, thr_…")
+      threadId: string2().describe("the Thread whose computer you are attaching, thr_… or a short id like BUD-34")
     },
     surfaces: ["cli"],
     toolset: "loop",
@@ -12024,7 +12065,7 @@ var ACTION_DEFINITIONS = [
     title: "Open a Thread computer",
     description: "Deprecated by AD-306: start work with computer_run_start(threadId, mode) instead; this alias remains one release and boots the parent Thread Computer, returning a computerSessionId. An optional owned active runId records a successful session attach as Run retention activity. Use it only for a legacy client that still addresses the parent by cms_ id; unsafe recovery is refused and unresolved newer workspace state stays fail-closed.",
     inputSchema: {
-      threadId: string2().describe("the Arbor Thread whose stable computer to open, thr_…"),
+      threadId: string2().describe("the Arbor Thread whose stable computer to open, thr_… or a short id like BUD-34"),
       runId: string2().optional().describe("optional owned active Run; successful open renews its retention deadline"),
       idempotencyKey: string2().trim().min(1).max(200).optional().describe("optional explicit key for ONE distinct logical open; omission reuses the durable profile/Thread/recipe identity; changed options require a distinct intent; retry unchanged after response loss and never mint a new key to bypass unresolved work"),
       vcpus: number2().int().min(1).max(4).optional().describe("optional container vCPU request"),
@@ -12039,7 +12080,7 @@ var ACTION_DEFINITIONS = [
     title: "Replace a Thread computer",
     description: "DESTRUCTIVE RECOVERY: Replace an incompatible active Computer generation from the Thread's effective recipe when Arbor reports structural recipe incompatibility. Preserves the old generation unless the successor restores supported state and passes health.",
     inputSchema: {
-      threadId: string2().describe("the Thread whose active Computer generation is replaced, thr_…"),
+      threadId: string2().describe("the Thread whose active Computer generation is replaced, thr_… or a short id like BUD-34"),
       idempotencyKey: string2().min(1).max(200).describe("stable key for this ONE replacement request; reuse it unchanged for retries"),
       reason: string2().min(1).max(500).describe("concise auditable reason for replacing the active generation")
     },
@@ -12052,7 +12093,7 @@ var ACTION_DEFINITIONS = [
     title: "Start a run",
     description: `Start an isolated write Run or shared/read Run with one idempotencyKey; pending admission returns runStartId for receipt observation while the lifecycle owner continues independently. Save work outside the temporary Computer and finish the Run when done; first use: read the Computer guide at ${AGENT_GUIDE_URLS.computer}.`,
     inputSchema: {
-      threadId: string2().optional().describe("the Thread whose Computer this Run works in, thr_…; the canonical Run-first front door"),
+      threadId: string2().optional().describe("the Thread whose Computer this Run works in, thr_… or a short id like BUD-34; the canonical Run-first front door"),
       computerSessionId: string2().optional().describe("legacy compatibility alternative to threadId: an existing parent computerSessionId, cms_…"),
       mode: _enum(["read", "write"]).describe("write for mutable work; read for shared inspection"),
       execution: _enum(["shared", "isolated"]).optional().describe("write Run placement; defaults to isolated. Use shared only for intentional live collaboration on the Thread Computer"),
@@ -12234,7 +12275,7 @@ var ACTION_DEFINITIONS = [
     title: "Capture public visual evidence",
     description: "Capture a 1280×720 screenshot of one public HTTPS URL as Thread evidence without opening the project runtime. Returns capture metadata plus ready-to-place attachments[].markdown; put that Markdown exactly where the image belongs and bind the matching attachmentIds, while localhost and authenticated pages remain unavailable and the capture does not judge correctness.",
     inputSchema: {
-      threadId: string2().describe("the Arbor Thread that will own the evidence, thr_…"),
+      threadId: string2().describe("the Arbor Thread that will own the evidence, thr_… or a short id like BUD-34"),
       targetUrl: url().refine((value) => value.startsWith("https://"), "targetUrl must use HTTPS").describe("one public HTTPS URL to capture")
     },
     surfaces: ["computer-mcp", "computer-cli"],
@@ -12321,7 +12362,7 @@ var ACTION_DEFINITIONS = [
       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 +12386,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,11 +12422,13 @@ var ACTION_DEFINITIONS = [
   },
   {
     name: "attachment_upload",
-    title: "Upload a local Thread file",
-    description: "Upload a local file with Node or Bun (SHA-256 → presigned PUT → attach, 100 MB cap)",
+    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.",
@@ -12395,8 +12438,9 @@ var ACTION_DEFINITIONS = [
 `),
     inputSchema: {
       threadId: string2().min(1),
-      file: string2().min(1).describe("local file path (or positional file); requires Node or Bun"),
-      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",
@@ -12515,7 +12559,7 @@ var ACTION_DEFINITIONS = [
     title: "Read a Thread computer",
     description: "Inspect a Thread's provider-free durable Computer recipe/materialization state, compatibility, recoverySafety, lineage, recent receipts, Runs, and reprovision outcomes; setup content and credentials stay redacted. This read never contacts execution; use computer_status for live readiness.",
     inputSchema: {
-      threadId: string2().describe("the Thread, thr_…"),
+      threadId: string2().describe("the Thread, thr_… or a short id like BUD-34"),
       lineageLimit: number2().int().min(1).max(100).optional().describe("recent receipts/lineage rows (default 20)")
     },
     surfaces: ["computer-mcp", "cli"],
@@ -12552,7 +12596,7 @@ var ACTION_DEFINITIONS = [
     title: "Set a thread's ways to help",
     description: "Set a thread's READ-ONLY 'ways to help' (AD-038) — a short, curated list of perspectives, skills, or concrete tasks orienting someone on how they could pitch in with THIS thread as it stands (e.g. 'a benchmark on cold-start latency'). It is thread-local and temporary: it is read inside `thread_get`, and it never rolls up into a space/topic orientation surface — a standing statement about what a room wants is the room's standing ways to help (`contributionLanes`, via `set_space_lanes`/`set_topic_lanes`, AD-222). Guidance you READ, NOT an obligation — that's `request`. Replaces the whole list; pass [] to clear.",
     inputSchema: {
-      threadId: string2().describe("the thread, thr_…"),
+      threadId: string2().describe("the thread, thr_… or a short id like BUD-34"),
       waysToHelp: proseList("the full ways-to-help list — replaces the existing one; [] clears it")
     },
     surfaces: ["cli"],
@@ -12564,7 +12608,7 @@ var ACTION_DEFINITIONS = [
     title: "Move a thread's lifecycle",
     description: transitionThreadActionDescription(),
     inputSchema: {
-      threadId: string2().describe("the thread to move, thr_…"),
+      threadId: string2().describe("the thread to move, thr_… or a short id like BUD-34"),
       to: string2().min(1).describe("label key, case-insensitive label name, or bare type (`resolved` still works as a type name)"),
       reason: string2().optional().describe("optional one-line why, recorded on the event"),
       rank: string2().max(THREAD_RANK_MAX).regex(THREAD_RANK_PATTERN).nullable().optional().describe("LexoRank in the destination column; omit to leave unchanged, null to restore recency. Combined with `--to` this is one atomic write — a bad rank moves nothing")
@@ -12650,7 +12694,7 @@ var ACTION_DEFINITIONS = [
     description: "Bind one Artifact to an existing same-Space Thread Live Preview, making the Artifact the durable entry point for that executable surface. Omit --thread-id to clear the binding; this changes no Artifact source/version and does not create or reconfigure a Computer.",
     inputSchema: {
       artifactId: string2().describe("the Artifact, art_…"),
-      threadId: string2().optional().describe("the configured Thread Live Preview to bind, thr_…; omit to clear")
+      threadId: string2().optional().describe("the configured Thread Live Preview to bind, thr_… or a short id like BUD-34; omit to clear")
     },
     surfaces: ["cli"],
     toolset: "artifacts",
@@ -12730,7 +12774,7 @@ var ACTION_DEFINITIONS = [
     title: "Request a contribution or review",
     description: "Request a contribution or review on a Thread: omit aboutContributionId for a contribution answered via respond, or pass it for a review answered only by stamp; explicitly target yourself for a normal Inbox obligation, target other people, or leave it open. Choose completion/deadline and optionally opensAt/opensIn to keep it dormant until scheduled delivery; fulfill a self-target through respond or use cancel_request to retire it.",
     inputSchema: {
-      threadId: string2().describe("the thread the request is in, thr_…"),
+      threadId: string2().describe("the thread the request is in, thr_… or a short id like BUD-34"),
       requestedAction: string2().optional().describe("a one-line 'what you're requesting'"),
       requestedType: _enum(CONTRIBUTION_TYPES).optional().describe("the contribution type you're HOPING for (e.g. evidence, decision) — a soft default on the responder's picker, never a constraint; omit for 'any contribution welcome'. Contribution asks only"),
       aboutContributionId: string2().optional().describe("PASS to request a REVIEW of this contribution (con_…, in the thread; met by a stamp, badges that card). OMIT to request a CONTRIBUTION on the thread (met by a respond)."),
@@ -12891,7 +12935,7 @@ var ACTION_DEFINITIONS = [
     title: "Read a thread",
     description: "Read one Thread as compact current context (distillate, requests, artifacts, recent tail, cursored unchanged checks) — not the durable transcript; pass view=full to read contribution bodies and attachments (including Markdown and authenticated URLs) and page history (contribLimit default 50) or all=true for the complete transcript. Read it before contributing so you can answer open requests correctly.",
     inputSchema: {
-      threadId: string2().describe("the thread id, e.g. thr_…"),
+      threadId: string2().describe("the thread id, e.g. thr_…, or its short id, e.g. BUD-34"),
       view: _enum(["full", "compact"]).optional().describe("MCP/CLI/API default compact = bounded decision-ready context; full = transcript page"),
       cursor: string2().optional().describe("compact reads only: cursor from the previous compact response; if context is unchanged the response collapses to a tiny unchanged envelope"),
       recentLimit: number2().int().min(1).max(20).optional().describe("compact reads only: latest contributions to include (default 6, max 20)"),
@@ -13062,7 +13106,7 @@ var ACTION_DEFINITIONS = [
     title: "Link a thread to a goal",
     description: "Record that a thread contributes to a goal — the many-to-many link that surfaces the goal on the thread's space and lists the thread under the goal. Idempotent. Reach for this once a thread's work clearly serves a goal; use `list_goals` to find the goal id.",
     inputSchema: {
-      threadId: string2().describe("the contributing thread, thr_…"),
+      threadId: string2().describe("the contributing thread, thr_… or a short id like BUD-34"),
       initiativeId: string2().describe("the goal it serves, ini_…")
     },
     surfaces: ["cli"],
@@ -13074,7 +13118,7 @@ var ACTION_DEFINITIONS = [
     title: "Unlink a thread from a goal",
     description: "Remove the link between a thread and a goal (the deliberate inverse of `link_thread_to_goal`). Idempotent. Reach for this when a thread no longer serves the goal it was attached to — the thread and the goal both stay; only the link is dropped.",
     inputSchema: {
-      threadId: string2().describe("the thread to unlink, thr_…"),
+      threadId: string2().describe("the thread to unlink, thr_… or a short id like BUD-34"),
       initiativeId: string2().describe("the goal to unlink it from, ini_…")
     },
     surfaces: ["cli"],
@@ -13099,7 +13143,7 @@ var ACTION_DEFINITIONS = [
     description: "List compact goals attached to one Space, or a Thread's linked goals plus its available pick list. Space lists are compact cards; Thread lists page only the available `all` list and keep `linked` complete; view=summary returns 3 active goals; status pages named lifecycles before the page.",
     inputSchema: {
       spaceId: string2().optional().describe("a Space whose attached goals to list, spc_…"),
-      threadId: string2().optional().describe("a Thread whose linked and available goals to list, thr_…"),
+      threadId: string2().optional().describe("a Thread whose linked and available goals to list, thr_… or a short id like BUD-34"),
       view: literal("summary").optional().describe("summary: Topics home — 3 most recently active goals (title + in-space linked Thread count). Ignores status. Omit for the attached list."),
       status: union([
         _enum(["active", "paused", "completed", "archived"]),
@@ -13153,6 +13197,7 @@ var ACTION_DEFINITIONS = [
     description: "Create a Space when work needs its own durable collaboration/governance boundary — its own membership, visibility, shared norms, and multiple durable areas; you become its first admin (org owner/admins always can, other members only when enabled), with open/private visibility and optional seeded members. If the work can live under an existing Space with the same people and governance, use a Topic instead.",
     inputSchema: {
       title: string2().min(1).describe("the space title"),
+      key: SPACE_KEY_INPUT.optional().describe("thread short-id prefix (BUD in BUD-34): 1-10 letters/digits, starting with a letter, unique in the org; default: the title's first three letters"),
       purpose: string2().optional().describe("why this boundary exists and what it is around — commonly a Product/System, Program/Function, Portfolio/Network, or Practice/Community — plus its dominant work modes (Build, Operate, Coordinate, Discuss, Share) when that helps; plain prose, not metadata syntax"),
       visibility: _enum(["open", "private"]).optional().describe("open (default) or private (invite-only)"),
       memberProfileIds: array(string2()).optional().describe("org profile ids to seed as members — agents added directly, humans get a pending invite")
@@ -13169,6 +13214,7 @@ var ACTION_DEFINITIONS = [
       spaceId: string2().describe("the space, spc_…"),
       purpose: string2().optional().describe("why this boundary exists and what it is around — commonly a Product/System, Program/Function, Portfolio/Network, or Practice/Community — plus its dominant work modes (Build, Operate, Coordinate, Discuss, Share) when that helps; plain prose, not metadata syntax"),
       title: string2().optional().describe("a new title for the space"),
+      key: SPACE_KEY_INPUT.optional().describe("a new thread short-id prefix (BUD in BUD-34), unique in the org; every thread's short id changes, the old ones stop resolving, and the old key stays reserved to this Space"),
       visibility: _enum(["open", "private"]).optional().describe("open or private (invite-only)"),
       stage: _enum(["exploration", "design", "implementation", "maintenance", "retired"]).optional().describe("set the lifecycle stage; retired archives the Space reversibly and restores with an active stage, but only when no Run is active/suspended and no App is serving"),
       attachWorkflow: string2().optional().describe("add a workflow to this Space's list: a built-in id (`standard`, `queue`, `content`, `experiment`, `funnel`) or a catalog `wfl_…` from `workflow_list`"),
@@ -13379,7 +13425,7 @@ var ACTION_DEFINITIONS = [
     title: "Inspect a thread (superadmin)",
     description: "Platform-operator only: read any thread by id across orgs (its contributions + authors), bypassing the per-org membership boundary for oversight.",
     inputSchema: {
-      threadId: string2().min(1).describe("the thread id, e.g. thr_…")
+      threadId: string2().min(1).describe("the canonical thread id, e.g. thr_… (admin reads are cross-org)")
     },
     surfaces: ["cli"],
     toolset: "admin",
@@ -13400,7 +13446,7 @@ var ACTION_DEFINITIONS = [
     description: "List compact goals attached to one Space, or the linked and available goals for one Thread. Space pages omit relatedThreads; Thread pages keep linked complete and page only the available `all` list; view=summary returns 3 active goals; status pages named lifecycles before the page; it cannot mutate a goal.",
     inputSchema: {
       spaceId: string2().optional().describe("a Space whose attached goals to list, spc_…"),
-      threadId: string2().optional().describe("a Thread whose linked and available goals to list, thr_…"),
+      threadId: string2().optional().describe("a Thread whose linked and available goals to list, thr_… or a short id like BUD-34"),
       view: literal("summary").optional().describe("summary: Topics home — 3 most recently active goals (title + in-space linked Thread count). Ignores status. Omit for the attached list."),
       status: union([
         _enum(["active", "paused", "completed", "archived"]),
@@ -13432,7 +13478,7 @@ var ACTION_DEFINITIONS = [
       threadIds: array(string2()).optional().describe("create: threads to link at birth"),
       id: string2().optional().describe("update/set_status: the goal, ini_…"),
       status: _enum(["active", "paused", "completed", "archived"]).optional().describe("set_status: the new lifecycle state"),
-      threadId: string2().optional().describe("link_thread/unlink_thread: the thread, thr_…"),
+      threadId: string2().optional().describe("link_thread/unlink_thread: the thread, thr_… or a short id like BUD-34"),
       initiativeId: string2().optional().describe("link/unlink/attach/detach: the goal, ini_…")
     },
     surfaces: ["mcp"],
@@ -13616,7 +13662,7 @@ var ACTION_DEFINITIONS = [
       computerSessionId: string2().optional().describe("create: the attached computer session that produced it, cms_…"),
       sourceContributionIds: array(string2()).optional().describe("create: contributions it distills"),
       artifactId: string2().optional().describe("edit/set_live_preview/set_snapshot: the Artifact, art_…"),
-      threadId: string2().optional().describe("set_live_preview: the configured Thread Live Preview, thr_…; omit to clear the binding"),
+      threadId: string2().optional().describe("set_live_preview: the configured Thread Live Preview, thr_… or a short id like BUD-34; omit to clear the binding"),
       baseVersion: number2().optional().describe("edit: the version you READ (from get/create) — stale base is rejected with the current source"),
       patches: array(object({ old: string2(), new: string2() })).optional().describe("edit: exact-match hunks applied in order, atomically; each old must match exactly once"),
       note: string2().optional().describe("edit: one-line summary of what changed"),
@@ -14291,7 +14337,7 @@ var ACTION_DEFINITIONS = [
       topicId: string2().optional().describe("topic_guidance/topic_lanes: the topic, top_…"),
       guidance: proseList("space_guidance/topic_guidance: full list, replaces; [] clears").optional(),
       contributionLanes: proseList("space_lanes/topic_lanes: full list of ways to help, replaces; [] clears").optional(),
-      threadId: string2().optional().describe("ways_to_help: the thread, thr_…"),
+      threadId: string2().optional().describe("ways_to_help: the thread, thr_… or a short id like BUD-34"),
       waysToHelp: proseList("ways_to_help: full list, replaces; [] clears").optional()
     },
     surfaces: ["mcp"],
@@ -14677,6 +14723,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}$/;
@@ -15051,7 +15110,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)
@@ -15061,8 +15120,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);
@@ -15072,6 +15130,9 @@ async function uploadLocalAttachment(executor, input, fetcher = fetch) {
     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 ([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 {
@@ -15117,6 +15178,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) {
@@ -15208,15 +15398,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;
@@ -15238,7 +15433,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) {
@@ -15266,7 +15461,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) {
@@ -15281,7 +15476,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 } : {},
@@ -15355,6 +15550,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)) {
@@ -15387,7 +15583,8 @@ function flagsForSchema(inputSchema) {
       required: !optional,
       nullable,
       description: description(inner) ?? description(raw),
-      literal: isProseList(inner)
+      literal: isProseList(inner),
+      verbatim: isVerbatimList(inner)
     };
   });
 }
@@ -15428,7 +15625,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
       });
@@ -15451,6 +15648,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();
@@ -15706,6 +15907,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)
@@ -15793,7 +15995,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}]`;
@@ -15819,7 +16025,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);
@@ -15901,10 +16111,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`);
@@ -15942,8 +16154,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;
@@ -15980,7 +16200,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.2",
+  "version": "0.24.4",
   "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",
@@ -27,7 +27,7 @@
     "access": "public"
   },
   "scripts": {
-    "arbor": "tsx src/bin.ts",
+    "arbor": "vpx src/bin.ts",
     "build": "bun build ./src/bin.ts --target=node --outfile=dist/arbor.js",
     "test": "vp test run --passWithNoTests",
     "typecheck": "tsc -b",
@@ -38,7 +38,6 @@
     "@arbor/core": "workspace:*",
     "@types/node": "^26.2.0",
     "just-bash": "3.4.2",
-    "tsx": "^4.20.6",
     "typescript": "^5.8.0",
     "vite-plus": "catalog:",
     "zod": "^4.4.3"