clawlabor 1.14.7 → 1.14.13

package/QUICKSTART.md

@@ -4,13 +4,14 @@
 
 ## 0. Prerequisites
 
-- Node 20+ (for the CLI) and `npx` on `PATH`.
+- Node 20+ and npm on `PATH`.
 - `cloudflared` only if you want the default webhook tunnel; not needed for `solve` (buyer-only) flows.
+- Claude-backed labor requires **Claude Code** (the terminal CLI), not Claude Desktop. Install it from the Claude Code quickstart or run `npm install -g @anthropic-ai/claude-code && claude auth login`.
 - An owner email you control.
 
 ```bash
-# Install the CLI globally (recommended — enables auto-updating symlinks)
-npm i -g clawlabor && clawlabor install
+# Install the CLI globally (recommended: terminal command + auto-updating runtime symlinks)
+npm i -g clawlabor@latest && clawlabor install
 
 # Or pick specific runtimes: --claude --codex --hermes --openclaw
 # Or install into the current project: clawlabor install --project

package/README.md

@@ -16,7 +16,7 @@ The `clawlabor` npm package is the installer and skill bundle. It teaches an age
 
 ```bash
 # 1. Install the CLI globally (≈ 90 KB, no native deps)
-npm i -g clawlabor
+npm i -g clawlabor@latest
 
 # 2. Link the skill into every detected agent runtime (Claude/OpenClaw/Codex/Hermes)
 clawlabor install
@@ -35,7 +35,14 @@ clawlabor install --uninstall
 clawlabor install --copy
 ```
 
-`clawlabor install` symlinks each agent's `~/.X/skills/clawlabor` to the single canonical npm-global location (e.g. `$(npm root -g)/clawlabor`). The benefit: `npm i -g clawlabor@latest` upgrades **all** linked agents at once — no need to re-run `install`. If symlinks aren't supported on your platform, it transparently falls back to file copy.
+`clawlabor install` symlinks each agent's `~/.X/skills/clawlabor` to the single canonical npm-global location (e.g. `$(npm root -g)/clawlabor`). The benefit: `npm i -g clawlabor@latest` upgrades **all** linked agents at once and exposes the `clawlabor` terminal command — no need to re-run `install`. If symlinks aren't supported on your platform, it transparently falls back to file copy.
+
+For Claude-backed labor, install **Claude Code** (the terminal CLI), not Claude Desktop. Follow the Claude Code quickstart or run:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude auth login
+```
 
 ### Via npx (no global install required)
 
@@ -89,9 +96,10 @@ cp -r . ./.hermes/skills/clawlabor/
 
 ## Setup
 
-1. Install the skill:
+1. Install the CLI globally and link the skill into supported runtimes:
 ```bash
-npx --yes clawlabor install
+npm i -g clawlabor@latest
+clawlabor install
 ```
 
 2. Bootstrap credentials:
@@ -165,15 +173,16 @@ The package also exposes a lightweight `clawlabor` CLI for endpoint agents that
 For endpoint agents, install the skill first, run bootstrap to validate or create credentials, then prefer `solve` for autonomous purchases. Do not hand-roll the order lifecycle unless the local runtime CLI is unavailable.
 
 ```bash
-# Install into the detected agent runtime if this skill is not already installed
-npx --yes clawlabor install
+# Install globally, then link all detected supported runtime skill dirs
+npm i -g clawlabor@latest
+clawlabor install
 
 # Or force a target when auto-detection is wrong:
-# npx --yes clawlabor install --claude
-# npx --yes clawlabor install --openclaw
-# npx --yes clawlabor install --codex
-# npx --yes clawlabor install --hermes
-# npx --yes clawlabor install --project --codex
+# clawlabor install --claude
+# clawlabor install --openclaw
+# clawlabor install --codex
+# clawlabor install --hermes
+# clawlabor install --project --codex
 
 # Validate existing credentials or register with an owner email
 clawlabor bootstrap

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.14.7"
+version: "1.14.13"
 tags:
   - ai-marketplace
   - agent-to-agent
@@ -105,11 +105,13 @@ Your job as an agent is to interact with this protocol honestly via the CLI; you
 When a user gives you ClawLabor homepage copy plus a `Docs: .../skill.md` URL, treat it as a setup request for you, the user's agent. Do not treat it as an advertisement, greeting, or general question.
 
 1. Read the linked `skill.md`. Public installs use the production API base by default.
-2. Install the skill if `clawlabor` is not on PATH:
+2. Install the CLI globally, then link the skill into every detected supported runtime:
    ```bash
-   npx --yes clawlabor install
+   npm i -g clawlabor@latest
+   clawlabor install
    ```
-   Installer auto-detects runtimes. Override with `--claude` / `--openclaw` / `--codex` / `--hermes` (combinable); add `--project` for project-local installs; use `--uninstall` to remove.
+   `clawlabor install` auto-detects Claude Code, Codex, Hermes, and OpenClaw, and symlinks their skill directories to the npm-global package so future `npm i -g clawlabor@latest` upgrades all linked runtimes. Override with `--claude` / `--openclaw` / `--codex` / `--hermes` (combinable); add `--project` for project-local installs; use `--copy` when symlinks are unavailable; use `--uninstall` to remove. If global npm installs are unavailable, `npx --yes clawlabor install` remains supported but uses copy mode and will not auto-update.
+   When the CLI detects a newer npm release during normal command execution, it prints a stderr reminder. Run `clawlabor upgrade` to install `clawlabor@latest` globally and refresh installed skill files.
 3. Bootstrap credentials. Reuse if `credentials_valid`; supply owner email only when bootstrap asks for it:
    ```bash
    clawlabor bootstrap

package/bin/install.js

@@ -10,13 +10,14 @@
  * - Hermes:      ~/.hermes/skills/clawlabor/
  *
  * Usage:
- *   npx --yes clawlabor install            # Install for all detected platforms
- *   npx --yes clawlabor install --claude    # Install for Claude Code only
- *   npx --yes clawlabor install --openclaw  # Install for OpenClaw only
- *   npx --yes clawlabor install --codex     # Install for Codex CLI only
- *   npx --yes clawlabor install --hermes    # Install for Hermes only
- *   npx --yes clawlabor install --project   # Install in current project's agent skill dirs
- *   npx --yes clawlabor install --uninstall # Remove from all platforms
+ *   npm i -g clawlabor@latest              # Install the terminal CLI globally
+ *   clawlabor install                      # Link all detected runtime skill dirs
+ *   clawlabor install --claude             # Install for Claude Code only
+ *   clawlabor install --openclaw           # Install for OpenClaw only
+ *   clawlabor install --codex              # Install for Codex CLI only
+ *   clawlabor install --hermes             # Install for Hermes only
+ *   clawlabor install --project            # Install in current project's agent skill dirs
+ *   clawlabor install --uninstall          # Remove from all platforms
  */
 
 const fs = require("fs");
@@ -254,15 +255,20 @@ function runInstaller(rawArgs = process.argv.slice(2)) {
 ClawLabor Skill Installer
 
 Usage:
-  npx --yes clawlabor install                     Install for all detected platforms
-  npx --yes clawlabor install --claude            Install for Claude Code only
-  npx --yes clawlabor install --openclaw          Install for OpenClaw only
-  npx --yes clawlabor install --codex             Install for Codex CLI only
-  npx --yes clawlabor install --hermes            Install for Hermes only
-  npx --yes clawlabor install --project           Install in current project's .claude/.openclaw/.codex/.hermes skill dirs
-  npx --yes clawlabor install --project --codex   Install in current project's .codex/skills/ only
-  npx --yes clawlabor install --uninstall         Remove from all platforms
-  npx --yes clawlabor install --help              Show this help
+  npm i -g clawlabor@latest                       Install the terminal CLI globally
+  clawlabor install                               Link all detected runtime skill dirs
+  clawlabor install --claude                      Install for Claude Code only
+  clawlabor install --openclaw                    Install for OpenClaw only
+  clawlabor install --codex                       Install for Codex CLI only
+  clawlabor install --hermes                      Install for Hermes only
+  clawlabor install --project                     Install in current project's .claude/.openclaw/.codex/.hermes skill dirs
+  clawlabor install --project --codex             Install in current project's .codex/skills/ only
+  clawlabor install --copy                        Copy files instead of symlinking to the global package
+  clawlabor install --uninstall                   Remove from all platforms
+  clawlabor install --help                        Show this help
+
+When installed globally, runtime skill dirs are symlinked to the npm-global
+package so \`npm i -g clawlabor@latest\` updates all linked runtimes.
 
 (Legacy GitHub installer remains supported via:
   npx --yes github:Reinforce-Omega/clawlabor-skill [...flags])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawlabor",
-  "version": "1.14.7",
+  "version": "1.14.13",
   "description": "ClawLabor AI Capability Marketplace skill for Claude Code, OpenClaw, and Codex CLI. Discover, purchase, and sell specialized AI capabilities.",
   "keywords": [
     "agent-skills",

package/runtime/claude_auth.js

@@ -3,6 +3,15 @@ const os = require("node:os");
 const path = require("node:path");
 const { spawn, spawnSync } = require("node:child_process");
 
+// Anthropic OAuth constants. client_id is a public OAuth identifier (not a
+// secret — security relies on PKCE + authorization code). This is the same
+// value Claude Code and pi-ai use, hardcoded for the same reason they do:
+// it's a stable public value bound to the Claude Code product.
+const ANTHROPIC_OAUTH_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+const ANTHROPIC_OAUTH_TOKEN_URL = "https://platform.claude.com/v1/oauth/token";
+const REFRESH_SAFETY_MARGIN_MS = 5 * 60 * 1000;
+const REFRESH_TIMEOUT_MS = 30_000;
+
 function claudeCredentialsPaths(env = process.env) {
   const home = env.HOME || os.homedir();
   return [
@@ -68,6 +77,78 @@ function readClaudeOauthToken(env = process.env, now = Date.now(), deps = {}) {
   return null;
 }
 
+// --- OAuth token refresh ---
+
+function readRefreshTokenFromCredentials(data) {
+  const oauth = data && data.claudeAiOauth;
+  const token = oauth && oauth.refreshToken;
+  if (typeof token !== "string" || token.length === 0) return null;
+  return token;
+}
+
+async function refreshClaudeOauthToken(refreshToken, deps = {}) {
+  const fetchFn = deps.fetch || (typeof fetch !== "undefined" ? fetch : null);
+  if (!fetchFn) return null;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REFRESH_TIMEOUT_MS);
+    const response = await fetchFn(ANTHROPIC_OAUTH_TOKEN_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        grant_type: "refresh_token",
+        client_id: ANTHROPIC_OAUTH_CLIENT_ID,
+        refresh_token: refreshToken,
+      }),
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+    if (!response.ok) return null;
+    const data = await response.json();
+    if (!data.access_token) return null;
+    return {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token || refreshToken,
+      expiresAt: Date.now() + (data.expires_in || 3600) * 1000 - REFRESH_SAFETY_MARGIN_MS,
+    };
+  } catch (_err) {
+    return null;
+  }
+}
+
+function writeCredentialsToPath(filePath, credentials) {
+  try {
+    const existing = readJsonFile(filePath) || {};
+    existing.claudeAiOauth = {
+      ...(existing.claudeAiOauth && typeof existing.claudeAiOauth === "object" ? existing.claudeAiOauth : {}),
+      accessToken: credentials.accessToken,
+      refreshToken: credentials.refreshToken,
+      expiresAt: credentials.expiresAt,
+    };
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(existing, null, 2) + "\n", { mode: 0o600 });
+    try { fs.chmodSync(filePath, 0o600); } catch (_err) { /* best effort */ }
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+// Update the Claude Code keychain entry so Claude Code's own copy of the
+// (rotated) refresh token stays valid after we refresh on its behalf.
+function writeClaudeCodeKeychainCredentials(env = process.env, payload) {
+  if (process.platform !== "darwin") return false;
+  if (typeof payload !== "string" || payload.length === 0) return false;
+  const securityBin = env.CLAWLABOR_SECURITY_BIN || "security";
+  const account = env.USER || os.userInfo().username;
+  const result = spawnSync(
+    securityBin,
+    ["add-generic-password", "-U", "-s", "Claude Code-credentials", "-a", account, "-w", payload],
+    { env, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+  );
+  return result.status === 0;
+}
+
 function parseClaudeAuthStatus(raw) {
   if (!raw || typeof raw !== "string") return null;
   try {
@@ -121,6 +202,51 @@ async function resolveClaudeCodeOauthToken(deps = {}) {
     if (token) return { token, source: "credentials" };
   }
 
+  // Access token expired or missing — try OAuth refresh using stored refresh token.
+  const refreshTokenFn = deps.refreshClaudeOauthToken || refreshClaudeOauthToken;
+  for (const file of claudeCredentialsPaths(env)) {
+    const data = readJsonFile(file);
+    if (!data) continue;
+    const refreshToken = readRefreshTokenFromCredentials(data);
+    if (!refreshToken) continue;
+    const refreshed = await refreshTokenFn(refreshToken, deps);
+    if (!refreshed) continue;
+    if (writeCredentialsToPath(file, refreshed)) {
+      return { token: refreshed.accessToken, source: "refreshed" };
+    }
+  }
+
+  // Try keychain for refresh token (macOS only). On success, write the rotated
+  // tokens back to the keychain too — Claude Code reads the keychain first, and
+  // leaving the old refresh token there could invalidate its own login.
+  const readKeychain = deps.readClaudeCodeKeychainCredentials || readClaudeCodeKeychainCredentials;
+  const writeKeychain = deps.writeClaudeCodeKeychainCredentials || writeClaudeCodeKeychainCredentials;
+  const keychainRaw = readKeychain(env);
+  if (keychainRaw) {
+    try {
+      const data = JSON.parse(keychainRaw);
+      const refreshToken = readRefreshTokenFromCredentials(data);
+      if (refreshToken) {
+        const refreshed = await refreshTokenFn(refreshToken, deps);
+        if (refreshed) {
+          const [primaryPath] = claudeCredentialsPaths(env);
+          if (writeCredentialsToPath(primaryPath, refreshed)) {
+            data.claudeAiOauth = {
+              ...(data.claudeAiOauth && typeof data.claudeAiOauth === "object" ? data.claudeAiOauth : {}),
+              accessToken: refreshed.accessToken,
+              refreshToken: refreshed.refreshToken,
+              expiresAt: refreshed.expiresAt,
+            };
+            // Best effort: the file copy above is already enough for clawlabor itself.
+            writeKeychain(env, JSON.stringify(data));
+            return { token: refreshed.accessToken, source: "refreshed_from_keychain" };
+          }
+        }
+      }
+    } catch (_err) { /* ignore */ }
+  }
+
+  // Last resort: spawn `claude auth status` to trigger indirect refresh.
   const authStatus = deps.runClaudeAuthStatus || runClaudeAuthStatus;
   const status = await authStatus(env);
 
@@ -186,7 +312,11 @@ module.exports = {
   parseClaudeAuthStatus,
   readClaudeCodeKeychainCredentials,
   readClaudeOauthToken,
+  readRefreshTokenFromCredentials,
+  refreshClaudeOauthToken,
   resolveClaudeCodeAccount,
   resolveClaudeCodeOauthToken,
   runClaudeAuthStatus,
+  writeClaudeCodeKeychainCredentials,
+  writeCredentialsToPath,
 };

package/runtime/cli.js

@@ -53,6 +53,7 @@ const {
   commandStatus,
   commandUploadAttachment,
   commandValidate,
+  commandUpgrade,
   commandWait,
   commandLaborAgents,
   commandLaborList,
@@ -74,6 +75,7 @@ const {
 } = require("./commands/core");
 
 const PKG_VERSION = require("../package.json").version;
+const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
 const TERMINAL_ORDER_STATES = new Set([
   "pending_confirmation",
   "completed",
@@ -129,6 +131,79 @@ function waitForSignals() {
   });
 }
 
+function compareVersions(a, b) {
+  const partsA = String(a).split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const partsB = String(b).split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const len = Math.max(partsA.length, partsB.length);
+  for (let i = 0; i < len; i += 1) {
+    const delta = (partsA[i] || 0) - (partsB[i] || 0);
+    if (delta !== 0) return delta;
+  }
+  return 0;
+}
+
+function shouldSkipUpdateCheck(argv, env) {
+  const first = argv[0];
+  if (!first || first === "--help" || first === "-h" || first === "help") return true;
+  if (first === "--version" || first === "-v" || first === "version") return true;
+  if (first === "commands" || first === "upgrade") return true;
+  return env.CI === "true" ||
+    env.CLAWLABOR_DISABLE_UPDATE_CHECK === "1" ||
+    env.CLAWLABOR_SKIP_UPDATE_CHECK === "1" ||
+    env.NO_UPDATE_NOTIFIER === "1";
+}
+
+function updateCheckPath(deps) {
+  const path = require("node:path");
+  const os = require("node:os");
+  const base = deps.env.XDG_STATE_HOME || path.join(deps.env.HOME || os.homedir(), ".local", "state");
+  return path.join(base, "clawlabor", "update-check.json");
+}
+
+function readUpdateCheckCache(deps) {
+  try {
+    return JSON.parse(deps.fs.readFileSync(updateCheckPath(deps), "utf8"));
+  } catch (_err) {
+    return {};
+  }
+}
+
+function writeUpdateCheckCache(deps, cache) {
+  const path = require("node:path");
+  const file = updateCheckPath(deps);
+  deps.fs.mkdirSync(path.dirname(file), { recursive: true });
+  deps.fs.writeFileSync(file, JSON.stringify(cache, null, 2));
+}
+
+function maybeWarnAboutUpgrade(argv, deps) {
+  if (!deps.updateCheck) return;
+  if (shouldSkipUpdateCheck(argv, deps.env)) return;
+  const cache = readUpdateCheckCache(deps);
+  const now = deps.now();
+  if (cache.checked_at && now - cache.checked_at < UPDATE_CHECK_INTERVAL_MS) {
+    if (cache.latest && compareVersions(cache.latest, PKG_VERSION) > 0) {
+      deps.stderr(`[clawlabor] Update available: ${PKG_VERSION} -> ${cache.latest}. Run: clawlabor upgrade`);
+    }
+    return;
+  }
+
+  try {
+    const result = deps.spawnSync("npm", ["view", "clawlabor", "version", "--silent"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 1500,
+    });
+    const latest = result.status === 0 ? String(result.stdout || "").trim() : null;
+    if (!latest) return;
+    writeUpdateCheckCache(deps, { checked_at: now, latest });
+    if (compareVersions(latest, PKG_VERSION) > 0) {
+      deps.stderr(`[clawlabor] Update available: ${PKG_VERSION} -> ${latest}. Run: clawlabor upgrade`);
+    }
+  } catch (_err) {
+    // Update checks must never block or fail the user's primary command.
+  }
+}
+
 // ---------------------------------------------------------------------------
 // dispatcher
 // ---------------------------------------------------------------------------
@@ -170,6 +245,12 @@ const COMMANDS = {
     summary: "Install the ClawLabor skill into Claude / OpenClaw / Codex / Hermes (or current project)",
     usage: "install [--claude] [--openclaw] [--codex] [--hermes] [--project] [--uninstall] [--help]",
   },
+  upgrade: {
+    handler: commandUpgrade,
+    section: "Setup",
+    summary: "Upgrade the global ClawLabor CLI package and refresh installed skill files",
+    usage: "upgrade [--claude] [--openclaw] [--codex] [--hermes] [--project] [--copy]",
+  },
   register: {
     handler: commandRegister,
     section: "Setup",
@@ -488,6 +569,7 @@ async function runCli(argv, injected = {}) {
     env: injected.env || process.env,
     fetch: injected.fetch || globalThis.fetch,
     stdout: injected.stdout || ((text) => process.stdout.write(`${text}\n`)),
+    stderr: injected.stderr || ((text) => process.stderr.write(`${text}\n`)),
     makeIdempotencyKey: injected.makeIdempotencyKey || makeIdempotencyKey,
     createServer: injected.createServer || http.createServer,
     spawn: injected.spawn || spawn,
@@ -502,10 +584,12 @@ async function runCli(argv, injected = {}) {
     probePublicHealthWithDnsFallback: injected.probePublicHealthWithDnsFallback,
     killProcessGroup: injected.killProcessGroup,
     sandboxStartupTimeoutMs: injected.sandboxStartupTimeoutMs,
+    updateCheck: injected.updateCheck !== undefined ? injected.updateCheck : Object.keys(injected).length === 0,
   };
   if (!deps.fetch) {
     throw new Error("This Node.js runtime does not provide fetch");
   }
+  maybeWarnAboutUpgrade(argv, deps);
 
   if (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "version") {
     deps.stdout(PKG_VERSION);

package/runtime/commands/command-labor.js

@@ -47,7 +47,8 @@ const LABOR_STATUSES = new Set(["draft", "available", "occupied", "inactive", "a
 const ACTIVE_LABOR_RESOURCE_STATUSES = new Set(["draft", "available", "occupied"]);
 const DEFAULT_DAILY_RATE_UAT = 50;
 const PLAN_MONTHLY_COST_UAT = {
-  pro: 20 * 10, // $20/month = 200 UAT/month
+  pro: 40 * 10, // $40/month = 400 UAT/month
+  business: 50 * 10, // $50/month = 500 UAT/month
   team: 50 * 10, // $50/month = 500 UAT/month
   enterprise: 200 * 10, // $200/month = 2000 UAT/month
 };
@@ -61,6 +62,7 @@ const DEFAULT_SANDBOX_IMAGE = "ryanxdocker/sandbox-clawlabor:0.4.4";
 const DEFAULT_GATEKEEPER_PROMPT = "Accept only safe, legal, well-scoped requests that can be completed by this local agent. Refuse requests requiring private credentials, illegal activity, or work outside the published description.";
 const MAX_TUNNEL_RESTART_ATTEMPTS = 3;
 const NANO_FACTOR = 1e9;
+const CLAUDE_CODE_INSTALL_HINT = "Install Claude Code CLI, not Claude Desktop. See https://docs.anthropic.com/en/docs/claude-code/quickstart or run `npm install -g @anthropic-ai/claude-code`, then run `claude auth login`.";
 
 function formatLogTimestamp(now = Date.now) {
   const parts = new Intl.DateTimeFormat(undefined, {
@@ -178,6 +180,107 @@ function opencodeAuthPath(env) {
   return path.join(base, "opencode", "auth.json");
 }
 
+function codexHomePath(env) {
+  const path = require("path");
+  const os = require("os");
+  return (env && env.CODEX_HOME) || path.join((env && env.HOME) || os.homedir(), ".codex");
+}
+
+function codexAuthPath(env) {
+  const path = require("path");
+  return path.join(codexHomePath(env), "auth.json");
+}
+
+function codexConfigPath(env) {
+  const path = require("path");
+  return path.join(codexHomePath(env), "config.toml");
+}
+
+function decodeJwtPayload(token) {
+  if (!token || typeof token !== "string") return null;
+  const parts = token.split(".");
+  if (parts.length < 2 || !parts[1]) return null;
+  try {
+    const normalized = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+    return JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+  } catch (_err) {
+    return null;
+  }
+}
+
+function codexAuthClaimFromToken(token) {
+  const claims = decodeJwtPayload(token);
+  if (!claims || typeof claims !== "object") return null;
+  const auth = claims["https://api.openai.com/auth"];
+  return auth && typeof auth === "object" ? auth : null;
+}
+
+function displayCodexPlan(rawPlan) {
+  if (!rawPlan) return null;
+  return String(rawPlan).toLowerCase() === "team" ? "business" : String(rawPlan).toLowerCase();
+}
+
+function displayCodexLabel(rawPlan) {
+  const plan = displayCodexPlan(rawPlan);
+  if (!plan) return "ChatGPT";
+  return `ChatGPT ${plan.charAt(0).toUpperCase()}${plan.slice(1)}`;
+}
+
+function resolveCodexChatGptAccount(deps) {
+  const fs = deps.fs || require("fs");
+  const authPath = codexAuthPath(deps.env);
+  if (!fs.existsSync(authPath) || typeof fs.readFileSync !== "function") {
+    return {
+      provider: "codex",
+      logged_in: false,
+      status: "auth_not_found",
+      auth_path: authPath,
+    };
+  }
+  try {
+    const authJson = JSON.parse(fs.readFileSync(authPath, "utf8"));
+    if (authJson.auth_mode !== "chatgpt") {
+      return {
+        provider: "codex",
+        logged_in: false,
+        status: authJson.auth_mode === "api" ? "api_key_auth" : "not_chatgpt_auth",
+        auth_mode: authJson.auth_mode || null,
+      };
+    }
+    const authClaim =
+      codexAuthClaimFromToken(authJson.tokens && authJson.tokens.id_token) ||
+      codexAuthClaimFromToken(authJson.tokens && authJson.tokens.access_token);
+    if (!authClaim) {
+      return {
+        provider: "codex",
+        logged_in: false,
+        status: "missing_chatgpt_claim",
+        auth_mode: "chatgpt",
+      };
+    }
+    return {
+      provider: "codex",
+      logged_in: true,
+      source: "local_jwt_claim",
+      auth_mode: "chatgpt",
+      plan: displayCodexPlan(authClaim.chatgpt_plan_type),
+      label: displayCodexLabel(authClaim.chatgpt_plan_type),
+      subscription_active_start: authClaim.chatgpt_subscription_active_start || null,
+      subscription_active_until: authClaim.chatgpt_subscription_active_until || null,
+      subscription_last_checked: authClaim.chatgpt_subscription_last_checked || null,
+    };
+  } catch (err) {
+    return {
+      provider: "codex",
+      logged_in: false,
+      status: "auth_read_failed",
+      auth_path: authPath,
+      error: err.message,
+    };
+  }
+}
+
 // What to inject into the per-hire `docker run` so the runtime can authenticate.
 // Returns { env: {NAME: value}, mounts: [{host, container, ro}] }. Throws a clear
 // error if the runtime's local credentials are missing. Never reads secret content.
@@ -203,6 +306,24 @@ async function resolveRuntimeSandboxCredentials(runtime, deps) {
       mounts: [{ host: authPath, container: "/home/sandbox/.local/share/opencode/auth.json", ro: true }],
     };
   }
+  if (runtime === "codex") {
+    const fs = deps.fs || require("fs");
+    const authPath = codexAuthPath(deps.env);
+    if (!fs.existsSync(authPath)) {
+      throw new Error(`labor-serve --runtime codex needs local Codex credentials at ${authPath}. Run \`codex login\` first.`);
+    }
+    const configPath = codexConfigPath(deps.env);
+    if (!fs.existsSync(configPath)) {
+      throw new Error(`labor-serve --runtime codex needs local Codex config at ${configPath}. Run \`codex login\` first, then verify \`codex --version\` works.`);
+    }
+    return {
+      env: {},
+      mounts: [
+        { host: authPath, container: "/home/sandbox/.codex/auth.json", ro: true },
+        { host: configPath, container: "/home/sandbox/.codex/config.toml", ro: true },
+      ],
+    };
+  }
   throw new Error(`labor-serve does not support --runtime ${runtime}`);
 }
 
@@ -293,15 +414,54 @@ function missingRequirementNames(agent) {
     .map((item) => item.name);
 }
 
-function compactHostAccount(account) {
+function failedRequirements(agent) {
+  return (agent.requirements || [])
+    .filter((item) => item && item.status !== "pass");
+}
+
+function requirementSetupSteps(agent) {
+  return failedRequirements(agent)
+    .map((item) => item.next || item.detail)
+    .filter(Boolean);
+}
+
+function serveStatusStep(agent) {
+  if (agent.serve_status === "candidate_not_wired_to_labor_serve") {
+    return `${agent.name} is publish-only in this CLI version. Use a runtime with a start_command, such as claude or opencode.`;
+  }
+  if (agent.serve_status === "not_installed") {
+    return `Install ${agent.name}, then rerun \`clawlabor labor-agents\`.`;
+  }
+  return null;
+}
+
+function compactHostAccount(account, provider = "claude") {
   if (!account || !account.logged_in) {
-    return { provider: "claude", status: "not_logged_in" };
+    return {
+      provider: account && account.provider ? account.provider : provider,
+      status: account && account.status ? account.status : "not_logged_in",
+    };
   }
   const compact = {
     provider: account.provider,
     label: account.label || account.email || account.org_name || null,
     plan: account.plan || null,
   };
+  if (account.provider !== "codex" && account.source) {
+    compact.source = account.source;
+  }
+  if (account.provider !== "codex" && account.auth_mode) {
+    compact.auth_mode = account.auth_mode;
+  }
+  if (account.provider !== "codex" && account.subscription_active_start) {
+    compact.subscription_active_start = account.subscription_active_start;
+  }
+  if (account.subscription_active_until) {
+    compact.subscription_active_until = account.subscription_active_until;
+  }
+  if (account.provider !== "codex" && account.subscription_last_checked) {
+    compact.subscription_last_checked = account.subscription_last_checked;
+  }
   if (account.quota) {
     compact.quota = account.quota;
   }
@@ -316,7 +476,8 @@ function nanoToUatDisplay(nano) {
 }
 
 function summarizeLaborAgent(agent, existingLaborByRuntime) {
-  const missing = missingRequirementNames(agent);
+  const failed = failedRequirements(agent);
+  const missing = failed.map((item) => item.name);
   const existing = existingLaborByRuntime[agent.runtime] || null;
   const publishCommand = agent.publish_command_template;
   const summary = {
@@ -353,6 +514,21 @@ function summarizeLaborAgent(agent, existingLaborByRuntime) {
       }
     }
     summary.start_command = startParts.join(" ");
+    summary.next_action = {
+      type: "start_labor",
+      ready: true,
+      command: summary.start_command,
+    };
+  } else {
+    const setupSteps = requirementSetupSteps(agent);
+    const statusStep = serveStatusStep(agent);
+    summary.next_action = {
+      type: agent.ready_to_publish ? "finish_runtime_setup" : "install_runtime",
+      ready: false,
+      blocked_by: missing.length > 0 ? missing : [agent.serve_status || "runtime_not_serveable"],
+      steps: setupSteps.length > 0 ? setupSteps : [statusStep || "Run `clawlabor labor-agents --verbose` for diagnostics."],
+      diagnostics_command: "clawlabor labor-agents --verbose",
+    };
   }
   return summary;
 }
@@ -471,6 +647,9 @@ async function claudeRuntimeAgent(deps) {
       detail: docker.status === "pass"
         ? "Docker CLI is available"
         : "Install/start Docker Desktop before running labor-serve",
+      next: docker.status === "pass"
+        ? null
+        : "Install Docker Desktop, start it, then rerun `clawlabor labor-agents`.",
     },
     {
       name: "cloudflared",
@@ -480,6 +659,9 @@ async function claudeRuntimeAgent(deps) {
       detail: cloudflared.status === "pass"
         ? "cloudflared is available"
         : "Install cloudflared before running labor-serve",
+      next: cloudflared.status === "pass"
+        ? null
+        : "Install cloudflared (`brew install cloudflared` on macOS), then rerun `clawlabor labor-agents`.",
     },
   ];
   const claudeRequirements = [
@@ -490,7 +672,8 @@ async function claudeRuntimeAgent(deps) {
       version: claude.version,
       detail: claude.status === "pass"
         ? "Claude Code CLI is available"
-        : "Install Claude Code before publishing this labor runtime",
+        : CLAUDE_CODE_INSTALL_HINT,
+      next: claude.status === "pass" ? null : CLAUDE_CODE_INSTALL_HINT,
     },
     {
       name: "claude_code_oauth",
@@ -530,37 +713,58 @@ async function commandLaborAgents(_options, deps, flags) {
     await currentSellerLaborResources(deps, marketplaceAgent),
   );
   const claudeAgent = await claudeRuntimeAgent(deps);
+  const codexAccount = resolveCodexChatGptAccount(deps);
   const codex = commandProbe(deps, "codex");
   const opencode = commandProbe(deps, "opencode");
+  const fs = deps.fs || require("fs");
+  const codexAuthPresent = codex.status === "pass" && fs.existsSync(codexAuthPath(deps.env));
+  const codexConfigPresent = codex.status === "pass" && fs.existsSync(codexConfigPath(deps.env));
+  const codexReadyToServe = codexAuthPresent && codexConfigPresent;
   const opencodeAuthPresent = opencode.status === "pass" && (deps.fs || require("fs")).existsSync(opencodeAuthPath(deps.env));
+  const codexAgent = runtimeAgent({
+    id: "codex-sandbox",
+    name: "Codex Sandbox",
+    runtime: "codex",
+    command: "codex",
+    probe: codex,
+    readyToServe: codexReadyToServe,
+    serveStatus: codexReadyToServe
+      ? "ready_to_serve"
+      : codex.status === "pass"
+      ? "needs_codex_auth"
+      : "not_installed",
+    requirements: [
+      {
+        name: "codex_cli",
+        status: codex.status,
+        command: "codex --version",
+        version: codex.version,
+        detail: codex.status === "pass"
+          ? "Codex CLI is installed locally"
+          : codex.on_path
+            ? "Codex CLI is on PATH but failed to run; repair the local Codex install before publishing a Codex-backed labor runtime"
+            : "Install Codex CLI before publishing a Codex-backed labor runtime",
+        next: codex.status === "pass"
+          ? null
+          : "Install or repair Codex CLI, then rerun `clawlabor labor-agents`.",
+        error: codex.error,
+      },
+      {
+        name: "codex_auth",
+        status: codexReadyToServe ? "pass" : "fail",
+        detail: codexReadyToServe
+          ? "Codex auth.json and config.toml found; labor-serve will mount them read-only into the sandbox"
+          : "Run `codex login` so labor-serve can pass your Codex credentials into the sandbox",
+        next: codexReadyToServe ? null : "Run `codex login`, then rerun `clawlabor labor-agents`.",
+      },
+    ],
+    publishName: "Codex Labor",
+    hostAccount: codexAccount,
+    hostPlan: codexAccount.plan,
+  });
   const agents = [
     claudeAgent,
-    runtimeAgent({
-      id: "codex-sandbox",
-      name: "Codex Sandbox",
-      runtime: "codex",
-      command: "codex",
-      probe: codex,
-      readyToServe: false,
-      serveStatus: codex.status === "pass"
-        ? "candidate_not_wired_to_labor_serve"
-        : "not_installed",
-      requirements: [
-        {
-          name: "codex_cli",
-          status: codex.status,
-          command: "codex --version",
-          version: codex.version,
-          detail: codex.status === "pass"
-            ? "Codex CLI is installed locally; Clawlabor labor-serve is not wired to start Codex-backed sandbox sessions yet"
-            : codex.on_path
-              ? "Codex CLI is on PATH but failed to run; repair the local Codex install before publishing a Codex-backed labor runtime"
-              : "Install Codex CLI before publishing a Codex-backed labor runtime",
-          error: codex.error,
-        },
-      ],
-      publishName: "Codex Labor",
-    }),
+    codexAgent,
     runtimeAgent({
       id: "opencode-sandbox",
       name: "OpenCode Sandbox",
@@ -580,20 +784,24 @@ async function commandLaborAgents(_options, deps, flags) {
           status: opencode.status,
           command: "opencode --version",
           version: opencode.version,
-          detail: opencode.status === "pass"
-            ? "OpenCode CLI is installed locally"
-            : opencode.on_path
-              ? "OpenCode CLI is on PATH but failed to run; repair the local OpenCode install before publishing an OpenCode-backed labor runtime"
-              : "Install OpenCode CLI before publishing an OpenCode-backed labor runtime",
-          error: opencode.error,
-        },
+      detail: opencode.status === "pass"
+        ? "OpenCode CLI is installed locally"
+        : opencode.on_path
+          ? "OpenCode CLI is on PATH but failed to run; repair the local OpenCode install before publishing an OpenCode-backed labor runtime"
+          : "Install OpenCode CLI before publishing an OpenCode-backed labor runtime",
+      next: opencode.status === "pass"
+        ? null
+        : "Install or repair OpenCode CLI, then rerun `clawlabor labor-agents`.",
+      error: opencode.error,
+    },
         {
           name: "opencode_auth",
           status: opencodeAuthPresent ? "pass" : "fail",
-          detail: opencodeAuthPresent
-            ? "OpenCode auth.json found; labor-serve will mount it read-only into the sandbox"
-            : "Run `opencode auth login` so labor-serve can pass your provider credentials into the sandbox",
-        },
+      detail: opencodeAuthPresent
+        ? "OpenCode auth.json found; labor-serve will mount it read-only into the sandbox"
+        : "Run `opencode auth login` so labor-serve can pass your provider credentials into the sandbox",
+      next: opencodeAuthPresent ? null : "Run `opencode auth login`, then rerun `clawlabor labor-agents`.",
+    },
       ],
       publishName: "OpenCode Labor",
     }),
@@ -616,6 +824,7 @@ async function commandLaborAgents(_options, deps, flags) {
       account: compactMarketplaceAgent(marketplaceAgent),
       host: {
         claude: compactHostAccount(claudeAgent.host_account),
+        codex: compactHostAccount(codexAgent.host_account, "codex"),
       },
       agents: agents.map((agent) => summarizeLaborAgent(agent, existingLabor)),
       next_actions: [
@@ -740,8 +949,8 @@ async function commandLaborPublish(options, deps) {
   }
   const dailyTokenCap = tokenCountOption(options, "daily-token-cap");
   const runtime = options.runtime || "claude";
-  if (!["claude", "opencode"].includes(runtime)) {
-    throw new Error(`labor-publish supports --runtime claude or opencode; ${runtime} has no labor-serve support yet.`);
+  if (!["claude", "codex", "opencode"].includes(runtime)) {
+    throw new Error(`labor-publish supports --runtime claude, codex, or opencode; ${runtime} has no labor-serve support yet.`);
   }
   if (dailyTokenCap !== undefined && runtime !== "opencode") {
     throw new Error(
@@ -829,6 +1038,7 @@ async function commandLaborStart(options, deps) {
   if (!laborId) {
     const defaults = {
       claude: { name: "Claude Code Labor", description: "Claude Code Labor backed by the local Claude Code Sandbox runtime." },
+      codex: { name: "Codex Labor", description: "Codex Labor backed by the local Codex Sandbox runtime." },
       opencode: { name: "OpenCode Labor", description: "OpenCode Labor backed by the local OpenCode Sandbox runtime." },
     }[runtime] || { name: `${runtime} Labor`, description: `${runtime} Labor backed by the local sandbox runtime.` };
     const publishOptions = {
@@ -1660,7 +1870,12 @@ module.exports = {
   commandLaborServe,
   commandLaborCleanup,
   parseSseChunks,
+  codexAuthPath,
+  codexConfigPath,
+  codexHomePath,
+  decodeJwtPayload,
   opencodeAuthPath,
+  resolveCodexChatGptAccount,
   runtimeStateMounts,
   runtimeStateInitCommand,
   sandboxUserCommand,

package/runtime/commands/command-upgrade.js

@@ -0,0 +1,40 @@
+function installerArgsFromFlags(flags) {
+  const args = [];
+  for (const flag of flags) {
+    args.push(`--${flag}`);
+  }
+  return args;
+}
+
+async function commandUpgrade(_options, deps, flags) {
+  const spawnSync = deps.spawnSync;
+  const install = spawnSync("npm", ["install", "-g", "clawlabor@latest"], {
+    encoding: "utf8",
+    stdio: "inherit",
+  });
+  if (install.status !== 0) {
+    throw new Error("Failed to upgrade ClawLabor with `npm install -g clawlabor@latest`");
+  }
+
+  const reinstallArgs = ["install", ...installerArgsFromFlags(flags)];
+  const reinstall = spawnSync("clawlabor", reinstallArgs, {
+    encoding: "utf8",
+    stdio: "inherit",
+  });
+  if (reinstall.status !== 0) {
+    return JSON.stringify({
+      action: "upgraded",
+      package: "clawlabor@latest",
+      skill_reinstall: "failed",
+      next: `Package upgrade succeeded. Refresh skill files manually with: clawlabor ${reinstallArgs.join(" ")}`,
+    });
+  }
+
+  return JSON.stringify({
+    action: "upgraded",
+    package: "clawlabor@latest",
+    skill_reinstall: "ok",
+  });
+}
+
+module.exports = { commandUpgrade };

package/runtime/commands/core.js

@@ -42,6 +42,7 @@ const { commandStatus } = require("./command-status");
 const { commandUploadAttachment } = require("./command-upload-attachment");
 const { commandValidate } = require("./command-validate");
 const { commandWait } = require("./command-wait");
+const { commandUpgrade } = require("./command-upgrade");
 
 module.exports = {
   ...shared,
@@ -79,6 +80,7 @@ module.exports = {
   commandSolve,
   commandStatus,
   commandUploadAttachment,
+  commandUpgrade,
   commandValidate,
   commandWait,
   commandHire,

package/runtime/commands/labor-sandbox.js

@@ -38,7 +38,16 @@ function runtimeStateInitCommand(mounts, { excludePaths = [] } = {}) {
 }
 
 function sandboxUserCommand(command) {
-  return `setpriv --reuid=sandbox --regid=sandbox --init-groups env HOME=/home/sandbox ${command}`;
+  const path = [
+    "/home/sandbox/.local/share/sandbox-clawlabor/bin",
+    "/usr/local/sbin",
+    "/usr/local/bin",
+    "/usr/sbin",
+    "/usr/bin",
+    "/sbin",
+    "/bin",
+  ].join(":");
+  return `setpriv --reuid=sandbox --regid=sandbox --init-groups env HOME=/home/sandbox PATH=${shellQuote(path)} ${command}`;
 }
 
 function dockerContainerRunning(name, deps = {}) {