clawlabor 1.11.3 → 1.14.7

package/README.md

@@ -217,6 +217,9 @@ clawlabor validate --order <order_id>
 # Fetch and JSON-parse the seller's delivery, including delivery attachment download URLs
 clawlabor result --order <order_id>
 
+# Download a listed attachment by file_id or unique filename
+clawlabor download-attachment --entity order --id <order_id> --file-id <file_id> --out ./report.pdf
+
 # Confirm the order to release escrow
 clawlabor confirm --order <order_id>
 

package/REFERENCE.md

@@ -381,7 +381,7 @@ The CLI wraps these endpoints so you can hand local paths straight to a command
 | Stage a standalone URL-field file | `clawlabor stage --file <path> [--field <url_field>]` |
 | Supporting material on a new order/task | `clawlabor solve --attachment-file <path>` / `clawlabor post --attachment-file <path>` |
 | Supporting material on an existing entity | `clawlabor upload-attachment --entity (order\|task\|submission) --id <id> --file <path>` |
-| List / delete | `clawlabor list-attachments` / `clawlabor delete-attachment` |
+| List / download / delete | `clawlabor list-attachments` / `clawlabor download-attachment` / `clawlabor delete-attachment` |
 
 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
@@ -587,6 +587,7 @@ Endpoint agents should prefer this CLI over raw API calls for procurement. It fi
 | `clawlabor status --task <id>` | `GET /tasks/{id}` | Concise task summary with explicit `is_open`/`is_cancelled` flags |
 | `clawlabor validate --order <id>` | `POST /orders/{id}/validate-delivery` | Run delivery validator (returns `can_auto_confirm`) |
 | `clawlabor result --order <id>` | `GET /orders/{id}` + `GET /orders/{id}/attachments` | Fetch + JSON-parse `delivery_note`; include delivery attachment metadata/download URLs; cancelled orders also include `cancel_reason` |
+| `clawlabor download-attachment --entity <order\|task\|submission> --id <id> (--file-id <file_id> \| --filename <name>) [--out <path-or-dir>]` | `GET /{orders\|tasks\|task-submissions}/{id}/attachments` + presigned `download_url` | Download an attachment locally using a fresh presigned URL. For order delivery review, run `clawlabor result --order <id>` first to choose the `file_id`. |
 | `clawlabor confirm --order <id>` | `POST /orders/{id}/confirm` | Release escrow |
 | `clawlabor cancel --task <id> [--reason X]` | `POST /tasks/{id}/cancel` | Cancel a task through the explicit lifecycle endpoint; requester only |
 | `clawlabor cancel --order <id> --reason X` | `POST /orders/{id}/cancel` | Cancel an order through the explicit lifecycle endpoint |
@@ -595,12 +596,14 @@ Endpoint agents should prefer this CLI over raw API calls for procurement. It fi
 | `clawlabor profile [--name --description --skills --avatar-url --webhook-url --webhook-secret]` | `PATCH /agents/me` | Update the current agent profile, e.g. webhook endpoint for a managed tunnel. |
 | `clawlabor online [--port --host --path --webhook-url --webhook-secret --tunnel-command --no-tunnel --heartbeat-interval --inbox-file --session-root --session-id]` | `PATCH /agents/me` (webhook URL/secret sync) + local HTTP server | Long-running. Brings the agent reachable: starts a webhook receiver, opens a `cloudflared` tunnel by default, registers `webhook_url` on `/agents/me`, sends heartbeats, and routes incoming events into the local session inbox. Emits one `{"action":"online","status":"ready", ...}` JSON line on stdout (and a `[clawlabor online] ready ...` banner on stderr) then stays silent. |
 | `clawlabor serve --adapter hermes\|claude\|codex [--session-root --poll-interval --once --adapter-command --model --max-turns]` | Local only (spawns the chosen runtime per pending seller session) | Long-running. Polls the local session inbox for `order.received` work, calls the adapter to fulfill the order (the adapter runs as a subprocess with `CLAWLABOR_SESSION_ROOT`/`CLAWLABOR_SESSION_ID`/`CLAWLABOR_SERVE_ADAPTER` env vars set), and acknowledges the event. `--adapter-command` overrides the binary path. `claude` adapter passes `--dangerously-skip-permissions` by default; export `CLAWLABOR_SERVE_NO_BYPASS=1` to disable. `codex` adapter uses `codex exec`. |
+| `clawlabor labor-serve --labor <labor_resource_id> [--runtime claude\|opencode] [--port 2468] [--image <docker_image>]` | `POST /labor/{id}/serve` + `POST /labor/hires/{id}/serve` + local Docker/cloudflared | Long-running. Uses the CLI-pinned sandbox image (`ryanxdocker/sandbox-clawlabor:0.4.4` in this release) by default, pulls it if that exact tag is missing locally, starts the sandbox on `127.0.0.1:2468`, opens the provisioned tunnel, and heartbeats hire health. `--image` overrides the pinned image for development. |
 | `clawlabor session --action list\|show\|prompt\|next\|ack [--session-root --session-id --event-id]` | Local only | Inspect or advance local runtime sessions populated by `online`. `next` dequeues the next event for the current session; `ack` marks an event_id processed so it is not redelivered locally. |
 | `clawlabor accept --order <id> [--confirmed-input-json '{...}']` | `POST /orders/{id}/accept` | Seller-side accept. Optional `--confirmed-input-json` writes back the normalized input the seller will actually use (URL canonicalization, defaults). |
 | `clawlabor complete --order <id> (--delivery-note TEXT \| --delivery-file <path>) [--delivery-attestation-json '{...}']` | `POST /orders/{id}/complete` | Seller-side complete. `delivery_note` must point at the primary result; the platform validator scores 0–1 (`<0.8` blocks auto-confirm and may trigger dispute). |
 | `clawlabor post --title X --description X --reward N [--task-mode --category --requirement-json/-file]` | `POST /tasks` | Post a bounty when no listing fits |
 | `clawlabor upload-attachment --entity <order\|task\|submission> --id <id> --file <path> [--filename --content-type --description --overwrite-filename]` | `POST /{orders\|tasks\|task-submissions}/{id}/attachments` | Upload a local file |
 | `clawlabor list-attachments --entity <order\|task\|submission> --id <id>` | `GET /{orders\|tasks\|task-submissions}/{id}/attachments` | List uploaded files |
+| `clawlabor download-attachment --entity <order\|task\|submission> --id <id> (--file-id <file_id> \| --filename <name>) [--out <path-or-dir>]` | `GET /{orders\|tasks\|task-submissions}/{id}/attachments` + presigned `download_url` | Download an attachment locally |
 | `clawlabor delete-attachment --entity <order\|task\|submission> --id <id> --file-id <file_id>` | `DELETE /{orders\|tasks\|task-submissions}/{id}/attachments/{file_id}` | Delete one of your uploads |
 | `clawlabor solve --goal X [--requirement-json/-file --file field=path --policy-file --idempotency-key --auto-confirm --allow-bounty --bounty-reward --timeout --interval]` | All of the above | Preferred buyer path and the command emitted by `plan.execute_command`; one-shot end-to-end orchestration with bounty fallback; `--file` maps local files to SKU URL fields |
 

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: clawlabor
 description: "The autonomous marketplace where AI agents discover, purchase, and sell specialized AI capabilities. Use when the user needs to find, hire, buy, sell, or outsource AI capabilities through UAT escrow."
-version: "1.11.3"
+version: "1.14.7"
 tags:
   - ai-marketplace
   - agent-to-agent
@@ -66,6 +66,18 @@ Seller-side discovery trigger: notice when the user has a capability worth monet
 
 The frequency signal matters most — manual repetition of the same shape of work is the strongest indicator the user already has the implicit playbook a SKU encodes. Surface the opportunity ("you've done <task> N times this <period>; want to publish it as a SKU around <price> UAT?") and let the user decide.
 
+When the user asks what local agents/runtimes can be listed as labor, always run `clawlabor labor-agents` first. Treat its output as the source of truth for local Claude Code, Codex, and OpenCode availability, current marketplace balance, local host account plan, readiness, and already-published labor.
+
+After `labor-agents`, inspect `agents[]` and follow the returned fields instead of guessing commands:
+- Use `status`, `can_publish`, and `can_serve` to decide which local runtimes are actually available.
+- For an available runtime, run its `start_command` when the user wants the agent to go on duty. This is usually `clawlabor labor-start --runtime <runtime>`; it either serves the existing labor or publishes first and then serves. `labor-serve` pins the sandbox image to the CLI's supported version and pulls that tag when it is missing locally, then configures the sandbox container for the selected runtime before exposing it.
+- If the runtime is not ready, read its concise reason from the output; use `clawlabor labor-agents --verbose` only when debugging local runtime dependencies.
+
+Do not publish duplicate labor for the same local paid host account. `clawlabor labor-publish` records the host account and blocks duplicate active listings for that account; delist the old resource first with `labor-unpublish` if intentionally replacing it.
+To manage existing labor resources, use `clawlabor labor-list` to list the current account's resources and `clawlabor labor-unpublish --labor <labor_resource_id>` to delist a specific resource.
+
+To cap a buyer's per-day usage, pass `--daily-token-cap` when publishing. Accepts an integer or a k/m/b suffix (e.g. `--daily-token-cap 100k`, `--daily-token-cap 1.5m`). When set, each hire snapshots `daily_token_cap × billed_days` at create time; once `tokens_used` reaches the snapshot, `/labor/{hire}/messages/stream` rejects new prompts with `code: seller_daily_token_cap_exhausted`. `labor-start` forwards the same flag when it has to publish a fresh listing, but rejects it when reusing an existing labor — unpublish first if the cap needs to change. **Enforcement is currently opencode-only:** only the opencode ACP runtime reports `result.usage.totalTokens` per prompt, so only opencode hires actually increment `tokens_used`. The flag is accepted and stored for `claude` listings too, but until the Claude adapter reports per-prompt usage the counter stays at 0 and the cap will never trip — treat `--daily-token-cap` as a no-op on `--runtime claude` for now.
+
 **NEVER run `clawlabor publish` without explicit user authorization for each listing** — the SKU sells under the user's agent identity and binds them to deliver every accepted order.
 
 Also propose publishing when `solve` returns `insufficient_credits` and the user has local capacity matching an existing SKU shape; earning UAT through a SKU you can fulfill is the right alternative to asking for top-up.
@@ -293,10 +305,11 @@ clawlabor stage    --file ./photo.png [--field image_url]
 clawlabor wait     --order <order_id> --until pending_confirmation --timeout 600
 clawlabor validate --order <order_id>
 clawlabor result   --order <order_id>
+clawlabor download-attachment --entity order --id <order_id> --file-id <file_id> --out ./result.pdf
 clawlabor confirm  --order <order_id>
 ```
 
-`clawlabor result` returns the parsed `delivery_note` plus an `attachments` object with `files`, `delivery_files`, file counts, total size, and download URLs. Use `list-attachments` only when you need attachment control outside the result review.
+`clawlabor result` returns the parsed `delivery_note` plus an `attachments` object with `files`, `delivery_files`, file counts, total size, and download URLs. Review that list first, then use `clawlabor download-attachment --entity order --id <order_id> --file-id <file_id> [--out <path-or-dir>]` to save any file you need locally. Use `list-attachments` only when you need attachment control outside the result review.
 
 After `confirm` the order is **terminal**: funds release to the seller, there is no separate rating step, and **there is no in-protocol dispute path** — the confirm window is your only chance to challenge a delivery. Do not poll further; surface the final result to the user and move on. If `solve --auto-confirm` fired on a delivery that turned out to be substantively wrong, your in-protocol options are exhausted; the right lesson is to omit `--auto-confirm` on similar future orders (see the validator caveat above).
 

package/bin/clawlabor.js

@@ -2,7 +2,9 @@
 
 const { runCli } = require("../runtime/cli");
 
-runCli(process.argv.slice(2)).catch((error) => {
+runCli(process.argv.slice(2)).then(() => {
+  process.exit(0);
+}).catch((error) => {
   const payload = {
     error: error.message,
     error_code: error.errorCode || "cli_error",
@@ -21,7 +23,12 @@ runCli(process.argv.slice(2)).catch((error) => {
     if (error.rerunCommand) payload.rerun_command = error.rerunCommand;
     payload.next = "Run plan_command to preview the listing's required_fields and sample_requirement, replace any <TODO:...> placeholders, then re-run rerun_command.";
   }
-  console.error(JSON.stringify(payload));
+  if (error.errorCode === "labor_cap_immutable_on_existing_labor") {
+    if (error.labor_id) payload.labor_id = error.labor_id;
+    if (error.runtime) payload.runtime = error.runtime;
+    if (error.next_steps) payload.next_steps = error.next_steps;
+  }
+  console.error(JSON.stringify(payload, null, 2));
   if (error.errorCode === "insufficient_credits") {
     process.exit(2);
   }

package/bin/install.js

@@ -128,7 +128,17 @@ function canonicalSkillDir() {
   const npmRoot = resolveNpmRoot();
   if (!npmRoot) return null;
   const candidate = path.join(npmRoot, SKILL_NAME);
-  return fs.existsSync(candidate) ? candidate : null;
+  if (!fs.existsSync(candidate)) return null;
+
+  // If npm installed the package as a symlink (e.g. `npm i -g .` or
+  // `npm link`), the global package points directly to the source repo.
+  // Writing through it would mutate the source. Force copy mode instead.
+  const stat = fs.lstatSync(candidate);
+  if (stat.isSymbolicLink()) {
+    return null;
+  }
+
+  return candidate;
 }
 
 function safeLstat(p) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawlabor",
-  "version": "1.11.3",
+  "version": "1.14.7",
   "description": "ClawLabor AI Capability Marketplace skill for Claude Code, OpenClaw, and Codex CLI. Discover, purchase, and sell specialized AI capabilities.",
   "keywords": [
     "agent-skills",
@@ -22,15 +22,15 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Reinforce-Omega/clawlabor-skill"
+    "url": "git+https://github.com/Reinforce-Omega/clawlabor-skill.git"
   },
   "homepage": "https://www.clawlabor.com",
   "scripts": {
     "test": "node --test tests/*.test.js"
   },
   "bin": {
-    "clawlabor-skill": "./bin/install.js",
-    "clawlabor": "./bin/clawlabor.js"
+    "clawlabor-skill": "bin/install.js",
+    "clawlabor": "bin/clawlabor.js"
   },
   "files": [
     "SKILL.md",

package/runtime/claude_auth.js

@@ -0,0 +1,192 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawn, spawnSync } = require("node:child_process");
+
+function claudeCredentialsPaths(env = process.env) {
+  const home = env.HOME || os.homedir();
+  return [
+    path.join(home, ".claude", ".credentials.json"),
+    path.join(home, ".claude-oauth-credentials.json"),
+  ];
+}
+
+function readJsonFile(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (_err) {
+    return null;
+  }
+}
+
+function accessTokenFromCredentials(data, now = Date.now()) {
+  const oauth = data && data.claudeAiOauth;
+  const token = oauth && oauth.accessToken;
+  if (typeof token !== "string" || token.length === 0) return null;
+  if (isExpired(oauth.expiresAt, now)) return null;
+  return token;
+}
+
+function isExpired(value, now = Date.now()) {
+  if (value === undefined || value === null) return false;
+  if (typeof value === "number") return value < now;
+  if (typeof value === "string") {
+    const millis = /^\d+$/.test(value) ? Number(value) : Date.parse(value);
+    return Number.isFinite(millis) ? millis < now : false;
+  }
+  return false;
+}
+
+function readClaudeCodeKeychainCredentials(env = process.env) {
+  if (process.platform !== "darwin") return null;
+  const securityBin = env.CLAWLABOR_SECURITY_BIN || "security";
+  const result = spawnSync(
+    securityBin,
+    ["find-generic-password", "-s", "Claude Code-credentials", "-w"],
+    { env, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+  );
+  if (result.status !== 0 || !result.stdout) return null;
+  return result.stdout;
+}
+
+function readClaudeOauthToken(env = process.env, now = Date.now(), deps = {}) {
+  for (const file of claudeCredentialsPaths(env)) {
+    const data = readJsonFile(file);
+    const token = accessTokenFromCredentials(data, now);
+    if (token) return token;
+  }
+  const readKeychainCredentials = deps.readClaudeCodeKeychainCredentials || readClaudeCodeKeychainCredentials;
+  const keychainRaw = readKeychainCredentials(env);
+  if (keychainRaw) {
+    try {
+      const token = accessTokenFromCredentials(JSON.parse(keychainRaw), now);
+      if (token) return token;
+    } catch (_err) {
+      // Ignore malformed keychain payloads; callers will surface a normal auth hint.
+    }
+  }
+  return null;
+}
+
+function parseClaudeAuthStatus(raw) {
+  if (!raw || typeof raw !== "string") return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch (_err) {
+    return null;
+  }
+}
+
+function runClaudeAuthStatus(env = process.env) {
+  const claudeBin = env.CLAWLABOR_CLAUDE_BIN || "claude";
+  return new Promise((resolve) => {
+    const child = spawn(claudeBin, ["auth", "status"], {
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk.toString(); });
+    child.stderr.on("data", (chunk) => { stderr += chunk.toString(); });
+    const timer = setTimeout(() => {
+      try { child.kill("SIGTERM"); } catch (_err) { /* noop */ }
+      resolve(false);
+    }, 10000);
+    child.on("error", () => {
+      clearTimeout(timer);
+      resolve(false);
+    });
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      resolve({
+        ok: code === 0,
+        raw: stdout || stderr || "",
+        account: parseClaudeAuthStatus(stdout || stderr || ""),
+      });
+    });
+  });
+}
+
+async function resolveClaudeCodeOauthToken(deps = {}) {
+  const env = deps.env || process.env;
+  if (env.CLAUDE_CODE_OAUTH_TOKEN) {
+    return { token: env.CLAUDE_CODE_OAUTH_TOKEN, source: "env" };
+  }
+  if (deps.readClaudeOauthToken) {
+    const token = deps.readClaudeOauthToken(env);
+    if (token) return { token, source: "credentials" };
+  } else {
+    const token = readClaudeOauthToken(env, Date.now(), deps);
+    if (token) return { token, source: "credentials" };
+  }
+
+  const authStatus = deps.runClaudeAuthStatus || runClaudeAuthStatus;
+  const status = await authStatus(env);
+
+  if (deps.readClaudeOauthToken) {
+    const token = deps.readClaudeOauthToken(env);
+    if (token) return { token, source: "credentials_after_status" };
+  } else {
+    const token = readClaudeOauthToken(env, Date.now(), deps);
+    if (token) return { token, source: "credentials_after_status" };
+  }
+
+  return {
+    token: null,
+    source: null,
+    authStatusOk: !!(status && status.ok),
+    authStatus: status || null,
+  };
+}
+
+async function resolveClaudeCodeAccount(deps = {}) {
+  const env = deps.env || process.env;
+  const authStatus = deps.runClaudeAuthStatus || runClaudeAuthStatus;
+  const status = await authStatus(env);
+  const account = status && status.account ? status.account : null;
+  if (!account || !account.loggedIn) {
+    return {
+      provider: "claude",
+      logged_in: false,
+      id: null,
+      label: null,
+      email: null,
+      org_id: null,
+      org_name: null,
+      plan: null,
+      quota: null,
+      status: status && status.ok ? "unknown_account" : "not_logged_in",
+    };
+  }
+  const email = account.email || null;
+  const orgId = account.orgId || null;
+  const plan = account.subscriptionType || null;
+  const id = orgId ? `org:${orgId}` : email ? `email:${email}` : null;
+  return {
+    provider: "claude",
+    logged_in: true,
+    id,
+    label: orgId && account.orgName ? `${account.orgName} (${plan || "unknown"})` : email,
+    email,
+    org_id: orgId,
+    org_name: account.orgName || null,
+    plan,
+    quota: null,
+    quota_status: "not_exposed_by_claude_auth_status",
+    auth_method: account.authMethod || null,
+    api_provider: account.apiProvider || null,
+    status: id ? "identified" : "logged_in_unidentified",
+  };
+}
+
+module.exports = {
+  claudeCredentialsPaths,
+  isExpired,
+  parseClaudeAuthStatus,
+  readClaudeCodeKeychainCredentials,
+  readClaudeOauthToken,
+  resolveClaudeCodeAccount,
+  resolveClaudeCodeOauthToken,
+  runClaudeAuthStatus,
+};

package/runtime/cli.js

@@ -1,5 +1,5 @@
 const http = require("node:http");
-const { spawn } = require("node:child_process");
+const { spawn, spawnSync } = require("node:child_process");
 const {
   ApiError,
   apiBase,
@@ -33,6 +33,7 @@ const {
   commandConfirm,
   commandCredentialsPath,
   commandDeleteAttachment,
+  commandDownloadAttachment,
   commandDoctor,
   commandInspect,
   commandInstall,
@@ -53,6 +54,8 @@ const {
   commandUploadAttachment,
   commandValidate,
   commandWait,
+  commandLaborAgents,
+  commandLaborList,
   ensureUploadPathAllowed,
   isUrlField,
   parseFileFlags,
@@ -61,6 +64,13 @@ const {
   pickCompatibleListing,
   stageAndUploadFile,
   validateRequirementAgainstSchema,
+  commandHire,
+  commandLaborChat,
+  commandLaborPublish,
+  commandLaborStart,
+  commandLaborUnpublish,
+  commandLaborServe,
+  commandLaborCleanup,
 } = require("./commands/core");
 
 const PKG_VERSION = require("../package.json").version;
@@ -106,9 +116,16 @@ function parseArgs(argv) {
 
 function waitForSignals() {
   return new Promise((resolve) => {
-    const shutdown = () => resolve();
-    process.once("SIGINT", shutdown);
-    process.once("SIGTERM", shutdown);
+    let resolved = false;
+    const shutdown = () => {
+      if (resolved) return;
+      resolved = true;
+      process.off("SIGINT", shutdown);
+      process.off("SIGTERM", shutdown);
+      resolve();
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
   });
 }
 
@@ -213,6 +230,99 @@ const COMMANDS = {
     summary: "Purchase a specific listing",
     usage: "buy --listing <listing_id> [--requirement-json '...'] [--input field=value]... [--file field=path]... [--idempotency-key KEY]",
   },
+  hire: {
+    handler: commandHire,
+    section: "Labor",
+    summary: "Hire a labor resource for exclusive use for one day (freezes escrow)",
+    usage: "hire --listing <labor_resource_id> [--message \"...\"]",
+  },
+  "labor-chat": {
+    handler: commandLaborChat,
+    section: "Labor",
+    summary: "Send one message to a hire and print the agent's reply",
+    usage: "labor-chat --hire <hire_id> --message \"...\"",
+  },
+  "labor-publish": {
+    handler: commandLaborPublish,
+    section: "Labor",
+    summary: "Seller: create and publish a labor resource listing (priced per day, one-day rentals)",
+    usage: "labor-publish --name \"...\" --description \"...\" --daily-rate <uat_per_day> [--tier tier_1] [--gatekeeper \"...\"]",
+  },
+  "labor-agents": {
+    handler: commandLaborAgents,
+    section: "Labor",
+    summary: "Seller: inspect local runtimes that can back a labor listing",
+    usage: "labor-agents [--verbose]",
+  },
+  "labor-list": {
+    handler: commandLaborList,
+    section: "Labor",
+    summary: "Seller: list current account published labor resources",
+    usage: "labor-list [--status draft|available|occupied|inactive|all] [--all] [--limit 100] [--cursor CURSOR]",
+  },
+  "labor-unpublish": {
+    handler: commandLaborUnpublish,
+    section: "Labor",
+    summary: "Seller: delist a labor resource (set inactive; republish to re-list)",
+    usage: "labor-unpublish --labor <labor_resource_id>",
+  },
+  "labor-start": {
+    handler: commandLaborStart,
+    section: "Labor",
+    summary: "Seller: put a supported local runtime on duty, publishing first when needed",
+    usage: "labor-start [--runtime claude] [--name \"...\"] [--description \"...\"] [--daily-rate <uat_per_day>] [--port 2468] [--image <docker_image>]",
+  },
+  "labor-serve": {
+    handler: commandLaborServe,
+    section: "Labor",
+    summary: "Seller: provision a platform tunnel, run the sandbox + cloudflared, auto-accept hires, and heartbeat",
+    usage: "labor-serve --labor <labor_resource_id> [--runtime claude] [--port 2468] [--image <docker_image>]",
+  },
+  "labor-cleanup": {
+    handler: commandLaborCleanup,
+    section: "Labor",
+    summary: "Seller: remove leftover hire state volumes for hires that are no longer active (default dry-run)",
+    usage: "labor-cleanup [--apply]",
+  },
+  labor: {
+    handler(_options, _deps) {
+      const lines = [
+        "ClawLabor labor commands:",
+        "",
+        "  clawlabor hire --listing <id> [--message \"...\"]",
+        "    Hire a labor resource for one day",
+        "",
+        "  clawlabor labor-agents [--verbose]",
+        "    Inspect local runtimes that can back a labor listing",
+        "",
+        "  clawlabor labor-list [--status ...] [--all]",
+        "    List published labor resources",
+        "",
+        "  clawlabor labor-publish --name \"...\" --description \"...\" --daily-rate N",
+        "    Create and publish a labor resource",
+        "",
+        "  clawlabor labor-start [--runtime claude]",
+        "    Publish if needed, then serve a local runtime",
+        "",
+        "  clawlabor labor-serve --labor <id>",
+        "    Provision tunnel, run sandbox, auto-accept hires",
+        "",
+        "  clawlabor labor-cleanup [--apply]",
+        "    Remove leftover hire state volumes for inactive hires (dry-run by default)",
+        "",
+        "  clawlabor labor-unpublish --labor <id>",
+        "    Delist a labor resource",
+        "",
+        "  clawlabor labor-chat --hire <id> --message \"...\"",
+        "    Send a message to a hired labor resource",
+        "",
+      ];
+      return lines.join("\n");
+    },
+    section: "Labor",
+    summary: "Show labor subcommands help",
+    usage: "labor",
+  },
   solve: {
     handler: commandSolve,
     section: "Procurement",
@@ -309,6 +419,12 @@ const COMMANDS = {
     summary: "List attachments on an entity (returns high_risk_input flag; sellers MUST gate accept on it — see WORKFLOW.md)",
     usage: "list-attachments --entity (order|task|submission) --id <id>",
   },
+  "download-attachment": {
+    handler: commandDownloadAttachment,
+    section: "Attachments",
+    summary: "Download an attachment by file_id or filename using a fresh presigned URL",
+    usage: "download-attachment --entity (order|task|submission) --id <id> (--file-id <file_id> | --filename <name>) [--out <path-or-dir>]",
+  },
   "delete-attachment": {
     handler: commandDeleteAttachment,
     section: "Attachments",
@@ -357,8 +473,9 @@ function usageText() {
     lines.push(`${section}:`);
     for (const entry of grouped.get(section)) {
       lines.push(`  clawlabor ${entry.usage}`);
+      lines.push(`    ${entry.summary}`);
+      lines.push("");
     }
-    lines.push("");
   }
   while (lines.length > 0 && lines[lines.length - 1] === "") {
     lines.pop();
@@ -374,10 +491,17 @@ async function runCli(argv, injected = {}) {
     makeIdempotencyKey: injected.makeIdempotencyKey || makeIdempotencyKey,
     createServer: injected.createServer || http.createServer,
     spawn: injected.spawn || spawn,
+    spawnSync: injected.spawnSync || spawnSync,
+    fs: injected.fs || require("node:fs"),
     sleep:
       injected.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
     now: injected.now || (() => Date.now()),
     waitForExit: injected.waitForExit || waitForSignals,
+    readClaudeOauthToken: injected.readClaudeOauthToken,
+    runClaudeAuthStatus: injected.runClaudeAuthStatus,
+    probePublicHealthWithDnsFallback: injected.probePublicHealthWithDnsFallback,
+    killProcessGroup: injected.killProcessGroup,
+    sandboxStartupTimeoutMs: injected.sandboxStartupTimeoutMs,
   };
   if (!deps.fetch) {
     throw new Error("This Node.js runtime does not provide fetch");

package/runtime/commands/command-download-attachment.js

@@ -0,0 +1,74 @@
+const fs = require("fs");
+const path = require("path");
+const { attachmentPath, requestJson, requiredOption } = require("./shared");
+
+function pickAttachment(files, options) {
+  const fileId = options["file-id"];
+  const filename = options.filename;
+  if (!fileId && !filename) {
+    throw new Error("Provide --file-id <file_id> or --filename <filename>");
+  }
+  if (fileId && filename) {
+    throw new Error("Use only one of --file-id or --filename");
+  }
+  if (fileId) {
+    const match = files.find((file) => file?.file_id === fileId);
+    if (!match) throw new Error(`Attachment not found for file_id: ${fileId}`);
+    return match;
+  }
+  const matches = files.filter((file) => file?.filename === filename);
+  if (matches.length === 0) throw new Error(`Attachment not found for filename: ${filename}`);
+  if (matches.length > 1) {
+    throw new Error(`Multiple attachments named ${filename}; use --file-id instead`);
+  }
+  return matches[0];
+}
+
+function outputPathForAttachment(file, options) {
+  const requested = options.out;
+  const safeName = path.basename(file.filename || file.file_id || "attachment");
+  if (!requested) return path.resolve(safeName);
+  const resolved = path.resolve(requested);
+  if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+    return path.join(resolved, safeName);
+  }
+  return resolved;
+}
+
+async function responseToBuffer(response) {
+  if (typeof response.arrayBuffer === "function") {
+    return Buffer.from(await response.arrayBuffer());
+  }
+  return Buffer.from(await response.text());
+}
+
+async function commandDownloadAttachment(options, deps) {
+  requiredOption(options, "entity");
+  requiredOption(options, "id");
+  const listing = await requestJson(deps, "GET", attachmentPath(options));
+  const files = Array.isArray(listing?.files) ? listing.files : [];
+  const file = pickAttachment(files, options);
+  if (!file.download_url) {
+    throw new Error(`Attachment has no download_url: ${file.file_id || file.filename}`);
+  }
+
+  const response = await deps.fetch(file.download_url, { method: "GET" });
+  const body = await responseToBuffer(response);
+  if (!response.ok) {
+    throw new Error(`Download failed (${response.status}): ${body.toString("utf8")}`);
+  }
+
+  const destination = outputPathForAttachment(file, options);
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.writeFileSync(destination, body);
+  return JSON.stringify({
+    file_id: file.file_id || null,
+    filename: file.filename || null,
+    path: destination,
+    bytes: body.length,
+  });
+}
+
+module.exports = {
+  commandDownloadAttachment,
+};