@allocator-one/harness-cli 1.13.0 → 1.15.0

package/dist/cli.js

@@ -1,25 +1,37 @@
 #!/usr/bin/env node
 import {
   ACTIVITY_MAX_LIMIT,
+  CLI_PACKAGE,
   CLI_VERSION,
   Client,
   CommandError,
   DEFAULT_BASE_URL,
+  EXIT_INTERRUPTED,
+  EXIT_JOB_ENDED,
+  EXIT_WAITING_FOR_PERSON,
+  EXPERT_ASSIGNMENTS_PATH,
+  EXPERT_LAPSED,
   HttpError,
+  JOBS_MAX_LIMIT,
+  JOBS_MAX_PAGES,
+  JOB_STATES,
   LocalError,
   RELATION_CREATE_TYPES,
   RELATION_UPDATE_TYPES,
+  STEER_MAX_CHARACTERS,
   TransportError,
   UpgradeRequiredError,
   UsageError,
   activity,
   archive,
+  assignments,
   attachImage,
   blocked,
   clean,
   close,
   comment,
   comments,
+  conditionList,
   create,
   defaultCredentialsPath,
   deleteComment,
@@ -30,8 +42,21 @@ import {
   docShow,
   docUpdate,
   editComment,
+  errorDetails,
+  expertSummary,
+  explainExpertRefusal,
   findRepoConfig,
+  gateSet,
+  instructionFrom,
+  isExpertToken,
   isHostTrusted,
+  jobCancel,
+  jobContinue,
+  jobPause,
+  jobShow,
+  jobSteer,
+  jobWatch,
+  jobsList,
   json,
   labelCreate,
   labelDelete,
@@ -48,24 +73,47 @@ import {
   memberSetRole,
   milestoneCreate,
   milestoneList,
+  planCreate,
+  planEdit,
+  planHold,
+  planRelease,
+  planShow,
+  prepareProcedureRun,
   prime,
+  procedureSave,
+  procedureShow,
   projectCreate,
   projectList,
   projectShow,
   projectUpdate,
   readCredentials,
+  readPlanFile,
   ready,
   relationAdd,
   relationList,
   relationRm,
   relationUpdate,
+  requireCapabilityId,
   requireCloseArgs,
   requireCommentId,
   requireIdentifiers,
+  requireJobId,
+  requireJobsArgs,
+  requirePlanId,
+  requireProcedureId,
+  requireProcedureName,
+  requireReadyClaimArgs,
+  requireSchemaView,
+  requireSearchQuery,
+  requireToolsOpts,
+  requiredTeam,
   resolveCacheHome,
   resolveConfig,
+  resolveTextSources,
   search,
   show,
+  skillsList,
+  startProcedureRun,
   stateAdd,
   stateDelete,
   stateOrder,
@@ -75,15 +123,21 @@ import {
   teamList,
   teamRename,
   teamSetDefault,
+  toolShow,
+  toolsDomains,
+  toolsList,
+  toolsSearch,
   trustHost,
   update,
   upload,
   userList,
   validateBaseUrl,
+  validateIdempotencyKey,
   version,
+  watchStopSignal,
   workflowStates,
   writeCredentials
-} from "./chunk-XFMECLOU.js";
+} from "./chunk-I2S2JVCQ.js";
 
 // src/cli.ts
 import { createInterface as createInterface2 } from "readline";
@@ -666,7 +720,9 @@ async function exchangeCode(baseUrl, code, verifier, options) {
 async function manualLogin(baseUrl, options) {
   const notify = options.notify ?? defaultNotify;
   const prompt = options.prompt ?? defaultPrompt;
-  notify(`Open ${baseUrl}/cli/login in a browser, authorize, and paste the token below.`);
+  notify(
+    `Open ${baseUrl}/cli/login in a browser, authorize, and paste the token below (an outside expert pastes the pxc_ credential minted in their expert view instead).`
+  );
   const token = (await prompt()).trim();
   if (token === "") return { ok: false, message: "no token entered" };
   return verifyAndStore(baseUrl, token, options);
@@ -674,13 +730,15 @@ async function manualLogin(baseUrl, options) {
 async function verifyAndStore(baseUrl, token, options) {
   const path = options.credentialsPath ?? defaultCredentialsPath(options.env ?? process.env);
   const client = bareClient(baseUrl, token, options);
+  const expert = isExpertToken(token);
   try {
-    await client.get("/api/v1/teams");
+    await client.get(expert ? EXPERT_ASSIGNMENTS_PATH : "/api/v1/teams");
   } catch (error) {
     if (error instanceof HttpError) {
+      const lapsed = expert && error.status === 401 ? ` \u2014 ${EXPERT_LAPSED}` : "";
       return {
         ok: false,
-        message: `the received token failed verification (${error.message}, HTTP ${error.status}) \u2014 nothing was stored`
+        message: `the received token failed verification (${error.message}, HTTP ${error.status}) \u2014 nothing was stored${lapsed}`
       };
     }
     if (error instanceof TransportError) {
@@ -696,33 +754,44 @@ async function verifyAndStore(baseUrl, token, options) {
   try {
     writeCredentials(path, baseUrl, token);
   } catch (error) {
-    await client.delete("/api/v1/session").catch(() => void 0);
+    await revokeSession(client, token);
     const detail = error instanceof Error ? error.message : String(error);
     return {
       ok: false,
-      message: `could not store credentials at ${path}: ${detail}`
+      message: `could not store credentials at ${path}: ${detail}` + (expert ? " (the pxc_ credential is still valid: revoke it in your expert view)" : "")
     };
   }
+  let supersededNote = "";
   if (superseded !== null) {
-    await bareClient(superseded.url, superseded.token, options).delete("/api/v1/session").catch(() => void 0);
+    await revokeSession(bareClient(superseded.url, superseded.token, options), superseded.token);
+    if (isExpertToken(superseded.token)) {
+      supersededNote = "The pxc_ credential stored before stays valid until it expires: revoke it in your expert view.\n";
+    }
   }
   return {
     ok: true,
     json: { url: baseUrl, credentials: path },
-    human: `Logged in to ${baseUrl} \u2014 login token stored at ${path} (valid ~30 days; harness logout revokes it).
-`
+    human: (expert ? `Stored an outside expert's pxc_ credential for ${baseUrl} at ${path} (it lasts at most 30 days; revoke it in your expert view \u2014 harness logout only forgets it). Commands now act as the expert: only assignments, conditions and gate work until you log in again.
+` : `Logged in to ${baseUrl} \u2014 login token stored at ${path} (valid ~30 days; harness logout revokes it).
+`) + supersededNote
   };
 }
+async function revokeSession(client, token) {
+  if (isExpertToken(token)) return false;
+  return client.delete("/api/v1/session").then(() => true).catch(() => false);
+}
 async function logout(options = {}) {
   const path = options.credentialsPath ?? defaultCredentialsPath(options.env ?? process.env);
   const stored = readCredentials(path);
   if (stored === null) {
+    const envToken = (options.env ?? process.env)["HARNESS_API_TOKEN"] ?? "";
     return {
       ok: false,
-      message: "No stored login to remove. A HARNESS_API_TOKEN from the environment is yours to manage \u2014 unset it, or disable the token in the admin UI."
+      message: "No stored login to remove. A HARNESS_API_TOKEN from the environment is yours to manage \u2014 " + (isExpertToken(envToken.trim()) ? "unset it, or revoke the pxc_ credential in your expert view." : "unset it, or disable the token in the admin UI.")
     };
   }
-  const revoked = await bareClient(stored.url, stored.token, options).delete("/api/v1/session").then(() => true).catch(() => false);
+  const expert = isExpertToken(stored.token);
+  const revoked = await revokeSession(bareClient(stored.url, stored.token, options), stored.token);
   const note = revoked ? "" : " (server-side revoke failed \u2014 the token still expires on its own)";
   try {
     deleteCredentials(path);
@@ -736,23 +805,36 @@ async function logout(options = {}) {
   return {
     ok: true,
     json: { logged_out: true, revoked },
-    human: `Logged out of ${stored.url}${note}.
+    human: expert ? `Forgot the outside expert's pxc_ credential for ${stored.url}. It stays valid until it expires: revoke it in your expert view to end it now.
+` : `Logged out of ${stored.url}${note}.
 `
   };
 }
 async function whoami(config, credentialSource) {
   const client = new Client(config);
+  const expert = isExpertToken(config.token);
+  let probe;
   try {
-    await client.get("/api/v1/stats");
+    probe = (await client.get(expert ? EXPERT_ASSIGNMENTS_PATH : "/api/v1/stats")).data;
   } catch (error) {
     if (error instanceof HttpError) {
       return {
         ok: false,
-        message: `signed in to ${config.baseUrl} with a ${credentialSource} credential, but it failed verification: ${error.message} (HTTP ${error.status})`
+        message: expert ? `signed in to ${config.baseUrl} with an outside expert's pxc_ credential (${credentialSource}), but it was refused: ${error.message} (HTTP ${error.status})${error.status === 401 ? ` \u2014 ${EXPERT_LAPSED}` : ""}` : `signed in to ${config.baseUrl} with a ${credentialSource} credential, but it failed verification: ${error.message} (HTTP ${error.status})`
       };
     }
     throw error;
   }
+  let seat = null;
+  if (expert) {
+    seat = expertSeat(probe);
+    if (seat === null) {
+      return {
+        ok: false,
+        message: `signed in to ${config.baseUrl} with an outside expert's pxc_ credential, but the assignments response carried no expert`
+      };
+    }
+  }
   const serverVersion = await client.serverVersion().catch(() => "unknown");
   const hostSourceLabels = {
     env: "HARNESS_API_URL",
@@ -761,6 +843,9 @@ async function whoami(config, credentialSource) {
     default: "workspace default"
   };
   const via = config.hostSource !== void 0 ? ` (via ${hostSourceLabels[config.hostSource]})` : "";
+  const expertLines = seat === null ? "" : `Expert:      ${expertSummary(seat)}
+Reaches:     its own assignments and the gates it owns on them (assignments, conditions, gate)
+`;
   return {
     ok: true,
     json: {
@@ -768,14 +853,24 @@ async function whoami(config, credentialSource) {
       source: credentialSource,
       verified: true,
       server_version: serverVersion,
-      host_source: config.hostSource
+      host_source: config.hostSource,
+      expert: seat
     },
     human: `Host:        ${config.baseUrl}${via}
-Credential:  ${credentialSource}
-Verified:    ok (server API ${serverVersion})
+Credential:  ${credentialSource}${seat === null ? "" : ", an outside expert's pxc_ credential"}
+` + expertLines + `Verified:    ok (server API ${serverVersion})
 `
   };
 }
+function expertSeat(data) {
+  if (!isRecord2(data) || !isRecord2(data["expert"])) return null;
+  const plan2 = isRecord2(data["plan"]) ? { id: data["plan"]["id"], status: data["plan"]["status"] } : null;
+  const steps = Array.isArray(data["assignments"]) ? data["assignments"].filter(isRecord2).length : 0;
+  return { id: data["expert"]["id"], role: data["expert"]["role"] ?? null, plan: plan2, assigned_steps: steps };
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function bareClient(baseUrl, token, options) {
   const config = {
     baseUrl: baseUrl.replace(/\/+$/, ""),
@@ -809,113 +904,6 @@ function defaultOpenBrowser(url) {
   }
 }
 
-// src/core/textinput.ts
-import { readFileSync, statSync } from "fs";
-import { isatty } from "tty";
-var STDIN_PATH = "-";
-var MAX_TEXT_BYTES = 1e6;
-function flagOf(name) {
-  return name.replace(/[A-Z]/g, (upper) => `-${upper.toLowerCase()}`);
-}
-function resolveTextSources(sources) {
-  const resolved = {};
-  const toRead = [];
-  let stdinClaimedBy;
-  for (const { name, inline, file } of sources) {
-    if (inline !== void 0 && file !== void 0) {
-      throw new UsageError(
-        `--${flagOf(name)} and --${flagOf(name)}-file both given \u2014 pass one; there is no precedence between them`
-      );
-    }
-    if (file === void 0) {
-      if (inline !== void 0) resolved[name] = inline;
-      continue;
-    }
-    if (file === STDIN_PATH) {
-      if (isatty(0)) {
-        throw new UsageError(
-          `--${flagOf(name)}-file - reads stdin, but stdin is a terminal \u2014 pipe something in or pass a path`
-        );
-      }
-      if (stdinClaimedBy !== void 0) {
-        throw new UsageError(
-          `--${flagOf(name)}-file and --${flagOf(stdinClaimedBy)}-file both read stdin \u2014 there is only one stream, so only one may be "-"`
-        );
-      }
-      stdinClaimedBy = name;
-    }
-    if (file !== STDIN_PATH) checkReadable(file, name);
-    toRead.push({ name, file });
-  }
-  for (const { name, file } of [...toRead].sort(byStdinLast)) {
-    resolved[name] = stripOneTrailingNewline(readTextFile(file, name));
-  }
-  return resolved;
-}
-function readTextFile(path, name) {
-  if (path === STDIN_PATH) {
-    let piped;
-    try {
-      piped = readFileSync(0);
-    } catch (error) {
-      throw new UsageError(`--${flagOf(name)}-file -: cannot read stdin (${describe(error)})`);
-    }
-    if (piped.length > MAX_TEXT_BYTES) {
-      throw new UsageError(oversize(`--${flagOf(name)}-file -`));
-    }
-    return decodeUtf8(piped, `--${flagOf(name)}-file -`);
-  }
-  const flag = `--${flagOf(name)}-file ${path}`;
-  let bytes;
-  try {
-    bytes = readFileSync(path);
-  } catch (error) {
-    throw new UsageError(`${flag}: ${describe(error)}`);
-  }
-  if (bytes.length > MAX_TEXT_BYTES) throw new UsageError(oversize(flag));
-  return decodeUtf8(bytes, flag);
-}
-function decodeUtf8(bytes, flag) {
-  try {
-    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-  } catch {
-    throw new UsageError(`${flag}: not valid UTF-8 \u2014 convert it first`);
-  }
-}
-function oversize(what) {
-  return `${what}: over ${MAX_TEXT_BYTES / 1e6} MB \u2014 that is not prose; check the path`;
-}
-function checkReadable(path, name) {
-  const flag = `--${flagOf(name)}-file ${path}`;
-  let stats2;
-  try {
-    stats2 = statSync(path);
-  } catch (error) {
-    throw new UsageError(`${flag}: ${describe(error)}`);
-  }
-  if (!stats2.isFile()) {
-    throw new UsageError(
-      `${flag}: ${stats2.isDirectory() ? "is a directory" : "not a regular file"}`
-    );
-  }
-  if (stats2.size > MAX_TEXT_BYTES) throw new UsageError(oversize(flag));
-}
-function byStdinLast(a, b) {
-  return Number(a.file === STDIN_PATH) - Number(b.file === STDIN_PATH);
-}
-function stripOneTrailingNewline(text) {
-  if (text.endsWith("\r\n")) return text.slice(0, -2);
-  if (text.endsWith("\n")) return text.slice(0, -1);
-  return text;
-}
-function describe(error) {
-  const code = error?.code;
-  if (code === "ENOENT") return "no such file";
-  if (code === "EISDIR") return "is a directory";
-  if (code === "EACCES") return "permission denied";
-  return error instanceof Error ? error.message : String(error);
-}
-
 // src/core/stdio.ts
 var BROKEN_PIPE_CODES = /* @__PURE__ */ new Set(["EPIPE", "ERR_STREAM_DESTROYED"]);
 function guardBrokenPipes(streams = [process.stdout, process.stderr]) {
@@ -926,6 +914,57 @@ function guardBrokenPipes(streams = [process.stdout, process.stderr]) {
   }
 }
 
+// src/invocation.ts
+import { basename } from "path";
+var OPERATOR_PACKAGE = "@allocator-one/operator";
+function invokedName(argv1 = process.argv[1], packageName = CLI_PACKAGE) {
+  const typed = basename(argv1 ?? "").replace(/\.[cm]?js$/i, "").toLowerCase();
+  if (typed === "operator" || typed === "harness") return typed;
+  return packageName === OPERATOR_PACKAGE ? "operator" : "harness";
+}
+var OPERATOR_COMMANDS = [
+  "run",
+  "jobs",
+  "job",
+  "watch",
+  "steer",
+  "cancel",
+  "pause",
+  "continue",
+  "procedure",
+  "plan",
+  "gate",
+  "conditions",
+  "assignments",
+  "tools",
+  "tool",
+  "skills",
+  "mcp"
+];
+var GENERAL_COMMANDS = [
+  "login",
+  "logout",
+  "whoami",
+  "version",
+  "keys"
+];
+var OPERATOR_HEADING = "Operator:";
+var ISSUES_HEADING = "Issues:";
+var GENERAL_HEADING = "General:";
+function layoutOperatorHelp(program2) {
+  const rank = (name) => {
+    const operator = OPERATOR_COMMANDS.indexOf(name);
+    if (operator !== -1) return operator;
+    return GENERAL_COMMANDS.includes(name) ? 2 * OPERATOR_COMMANDS.length : OPERATOR_COMMANDS.length;
+  };
+  const heading = (name) => OPERATOR_COMMANDS.includes(name) ? OPERATOR_HEADING : GENERAL_COMMANDS.includes(name) ? GENERAL_HEADING : ISSUES_HEADING;
+  for (const command of program2.commands) command.helpGroup(heading(command.name()));
+  program2.commands.sort(
+    (left, right) => rank(left.name()) - rank(right.name())
+  );
+  program2.commandsGroup(GENERAL_HEADING).helpCommand(true);
+}
+
 // src/core/upgrade.ts
 import { spawn as spawn2, spawnSync } from "child_process";
 import {
@@ -934,20 +973,26 @@ import {
   existsSync,
   linkSync,
   mkdirSync,
-  readFileSync as readFileSync2,
+  readFileSync,
   realpathSync,
   renameSync,
   rmSync,
-  statSync as statSync2,
+  statSync,
   writeFileSync
 } from "fs";
-import { basename, dirname, join as join2, parse, sep } from "path";
+import { basename as basename2, dirname, join as join2, parse, sep } from "path";
 import { fileURLToPath } from "url";
 var PACKAGE_NAME = "@allocator-one/harness-cli";
+var PACKAGE_NAMES = [PACKAGE_NAME, OPERATOR_PACKAGE];
 var UPGRADE_INSTALL_SPEC = `${PACKAGE_NAME}@latest`;
+function upgradeInstallSpec(install) {
+  return `${install.packageName ?? PACKAGE_NAME}@latest`;
+}
 var UPDATE_CHECK_COMMAND = "__update-check";
 var REEXEC_SENTINEL = "HARNESS_UPGRADED";
-var DEFAULT_REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+function latestUrl(packageName = PACKAGE_NAME) {
+  return `https://registry.npmjs.org/${packageName}/latest`;
+}
 var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
 var REGISTRY_TIMEOUT_MS = 5e3;
 var NPM_ROOT_TIMEOUT_MS = 15e3;
@@ -960,28 +1005,31 @@ function detectInstall(from = fileURLToPath(import.meta.url)) {
     nodeModules: null
   };
   if (from.split(sep).includes("_npx")) return { ...unknown, kind: "npx" };
-  const packageRoot = findPackageRoot(from);
-  if (packageRoot === null) return unknown;
+  const found = findPackageRoot(from);
+  if (found === null) return unknown;
+  const { packageRoot, packageName } = found;
   if (existsSync(join2(packageRoot, ".git"))) {
-    return { kind: "checkout", packageRoot, nodeModules: null };
+    return { kind: "checkout", packageRoot, packageName, nodeModules: null };
   }
   const nodeModules = enclosingNodeModules(packageRoot);
-  if (nodeModules === null) return { ...unknown, packageRoot };
+  if (nodeModules === null) return { ...unknown, packageRoot, packageName };
   const kind = existsSync(join2(nodeModules, ".bin")) ? "local" : "global";
-  return { kind, packageRoot, nodeModules };
+  return { kind, packageRoot, packageName, nodeModules };
 }
 function findPackageRoot(from) {
   let dir = dirname(from);
   const { root } = parse(dir);
   for (; ; ) {
-    if (packageNameAt(join2(dir, "package.json")) === PACKAGE_NAME) return dir;
+    const name = packageNameAt(join2(dir, "package.json"));
+    if (name !== null && PACKAGE_NAMES.includes(name))
+      return { packageRoot: dir, packageName: name };
     if (dir === root) return null;
     dir = dirname(dir);
   }
 }
 function packageNameAt(path) {
   try {
-    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
     if (typeof parsed !== "object" || parsed === null) return null;
     const name = parsed["name"];
     return typeof name === "string" ? name : null;
@@ -992,7 +1040,7 @@ function packageNameAt(path) {
 function versionAt(packageRoot) {
   try {
     const parsed = JSON.parse(
-      readFileSync2(join2(packageRoot, "package.json"), "utf8")
+      readFileSync(join2(packageRoot, "package.json"), "utf8")
     );
     if (typeof parsed !== "object" || parsed === null) return null;
     const version2 = parsed["version"];
@@ -1005,7 +1053,7 @@ function enclosingNodeModules(packageRoot) {
   let dir = dirname(packageRoot);
   const { root } = parse(dir);
   for (; ; ) {
-    if (basename(dir) === "node_modules") return dir;
+    if (basename2(dir) === "node_modules") return dir;
     if (dir === root) return null;
     dir = dirname(dir);
   }
@@ -1052,12 +1100,15 @@ function comparePrerelease(left, right) {
   }
   return 0;
 }
-function stampPath(env = process.env) {
-  return join2(resolveCacheHome(env), "harness", "update-check.json");
+function stampPath(env = process.env, packageName = PACKAGE_NAME) {
+  const file = packageName === PACKAGE_NAME ? "update-check.json" : `update-check-${packageName.replace(/^@[^/]+\//, "")}.json`;
+  return join2(resolveCacheHome(env), "harness", file);
 }
-function readStamp(env = process.env) {
+function readStamp(env = process.env, packageName = PACKAGE_NAME) {
   try {
-    const parsed = JSON.parse(readFileSync2(stampPath(env), "utf8"));
+    const parsed = JSON.parse(
+      readFileSync(stampPath(env, packageName), "utf8")
+    );
     if (typeof parsed !== "object" || parsed === null) return null;
     const record = parsed;
     const checkedAt = record["checkedAt"];
@@ -1069,10 +1120,10 @@ function readStamp(env = process.env) {
     return null;
   }
 }
-function writeStamp(stamp, env = process.env) {
-  const path = stampPath(env);
+function writeStamp(stamp, env = process.env, packageName = PACKAGE_NAME) {
+  const path = stampPath(env, packageName);
   const temporary = `${path}.${process.pid}.tmp`;
-  const latest = stamp.latest ?? readStamp(env)?.latest ?? null;
+  const latest = stamp.latest ?? readStamp(env, packageName)?.latest ?? null;
   try {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(temporary, JSON.stringify({ ...stamp, latest }) + "\n");
@@ -1090,9 +1141,10 @@ function updateCheck(options = {}) {
   if (!checksEnabled(env)) return null;
   const install = options.install ?? detectInstall();
   if (install.kind !== "global" && install.kind !== "local") return null;
-  const stamp = readStamp(env);
+  const packageName = install.packageName ?? PACKAGE_NAME;
+  const stamp = readStamp(env, packageName);
   if (stamp === null || now - stamp.checkedAt >= CHECK_INTERVAL_MS) {
-    writeStamp({ checkedAt: now, latest: stamp?.latest ?? null }, env);
+    writeStamp({ checkedAt: now, latest: stamp?.latest ?? null }, env, packageName);
     (options.refresh ?? spawnRefresh)();
   }
   if (stamp !== null && stamp.latest !== null && isNewer(stamp.latest, CLI_VERSION)) {
@@ -1102,7 +1154,7 @@ function updateCheck(options = {}) {
   return null;
 }
 function upgradeHint(install) {
-  return install.kind === "local" ? `npm i ${PACKAGE_NAME}@latest` : `npm i -g ${PACKAGE_NAME}@latest`;
+  return install.kind === "local" ? `npm i ${upgradeInstallSpec(install)}` : `npm i -g ${upgradeInstallSpec(install)}`;
 }
 function spawnRefresh() {
   const self = process.argv[1];
@@ -1118,13 +1170,17 @@ function spawnRefresh() {
   } catch {
   }
 }
-async function performUpdateCheck(env = process.env, now = Date.now()) {
+async function performUpdateCheck(env = process.env, now = Date.now(), packageName = detectInstall().packageName ?? PACKAGE_NAME) {
   if (!checksEnabled(env)) return;
-  writeStamp({ checkedAt: now, latest: await fetchLatestVersion(env) }, env);
+  writeStamp(
+    { checkedAt: now, latest: await fetchLatestVersion(env, packageName) },
+    env,
+    packageName
+  );
 }
-async function fetchLatestVersion(env) {
+async function fetchLatestVersion(env, packageName) {
   const configured = env["HARNESS_REGISTRY_URL"];
-  const url = configured !== void 0 && configured.trim() !== "" ? configured.trim() : DEFAULT_REGISTRY_URL;
+  const url = configured !== void 0 && configured.trim() !== "" ? configured.trim() : latestUrl(packageName);
   try {
     const response = await fetch(url, {
       headers: { accept: "application/json" },
@@ -1242,8 +1298,10 @@ function npmInstallGlobal(install, stillHeld) {
       detail: "lost the upgrade lock while preparing \u2014 another process took over"
     };
   }
-  process.stderr.write(`harness: upgrading ${PACKAGE_NAME} \u2026
-`);
+  process.stderr.write(
+    `harness: upgrading ${install.packageName ?? PACKAGE_NAME} \u2026
+`
+  );
   const args = [
     "install",
     "--global",
@@ -1252,7 +1310,7 @@ function npmInstallGlobal(install, stillHeld) {
     "--no-fund",
     "--no-update-notifier",
     "--loglevel=error",
-    UPGRADE_INSTALL_SPEC
+    upgradeInstallSpec(install)
   ];
   const result = spawnSync(npmCommand(), args, {
     // npm's diagnostics belong on stderr with ours; stdout stays the
@@ -1362,8 +1420,8 @@ function releaseLock(lock) {
 }
 function readHolder(path) {
   try {
-    const mtimeMs = statSync2(path).mtimeMs;
-    const pid = Number.parseInt(readFileSync2(path, "utf8").trim(), 10);
+    const mtimeMs = statSync(path).mtimeMs;
+    const pid = Number.parseInt(readFileSync(path, "utf8").trim(), 10);
     return { pid: Number.isInteger(pid) && pid > 0 ? pid : null, mtimeMs };
   } catch {
     return null;
@@ -1414,7 +1472,10 @@ function exitWith(code) {
 }
 guardBrokenPipes();
 var program = new Command();
-program.name("harness").description("issue tracking for humans and agents (harness.infra.one)").exitOverride().configureOutput({
+var invokedAs = invokedName();
+program.name(invokedAs).description(
+  invokedAs === "operator" ? "drive Operator from the terminal and any agent, with Harness issue tracking alongside (harness.infra.one)" : "issue tracking for humans and agents (harness.infra.one)"
+).exitOverride().configureOutput({
   writeOut: (text) => process.stdout.write(text),
   writeErr: (text) => process.stderr.write(text)
 });
@@ -1513,7 +1574,7 @@ async function execute(config, jsonFlag, mutating, run) {
     process.stdout.write(jsonFlag ? json(output.json) : output.human);
     return exitWith(output.exitCode ?? (output.partial === true ? 1 : 0));
   } catch (error) {
-    return fail(error, hostNotice);
+    return fail(explainExpertRefusal(error, config.token), hostNotice);
   }
 }
 async function fail(error, hostNotice) {
@@ -1557,17 +1618,11 @@ async function fail(error, hostNotice) {
   }
   throw error;
 }
-function errorDetails(body) {
-  const details = body["details"];
-  if (typeof details !== "object" || details === null || Array.isArray(details))
-    return "";
-  return Object.entries(details).map(([field, messages]) => {
-    const text = Array.isArray(messages) ? messages.map(String).join("; ") : String(messages);
-    return `
-  ${clean(field)}: ${clean(text)}`;
-  }).join("");
-}
-program.command("ready").description("issues ready to work, highest priority first").option("--claim", "atomically claim the first claimable issue").option("--team <key>", "team filter").option("--limit <n>", "page size", integer).option("--page <n>", "page number", integer).option("--all", "follow every page").option("--json", "emit JSON").action(async (opts) => {
+program.command("ready").description("issues ready to work, highest priority first").option(
+  "--claim",
+  "claim the team's next ready, unassigned issue in one server-side request (team from --team, HARNESS_TEAM or the repo config; no paging flags)"
+).option("--team <key>", "team filter; with --claim, the team to claim from").option("--limit <n>", "page size", integer).option("--page <n>", "page number", integer).option("--all", "follow every page").option("--json", "emit JSON").action(async (opts) => {
+  if (opts.claim === true) requireReadyClaimArgs(opts);
   await withConfig(
     opts.json === true,
     opts.claim === true,
@@ -1618,7 +1673,7 @@ program.command("show").description("full issue detail; downloads attached image
     });
   }
 );
-program.command("activity").description("mixed issue activity: comments, creation, state and assignee changes").argument("[id]").option(
+program.command("activity").description("mixed issue activity: comments, creation, state, assignee, wait-condition and field changes").argument("[id]").option(
   "--limit <n>",
   `entries per page (default 20, max ${ACTIVITY_MAX_LIMIT})`,
   activityLimit
@@ -1814,6 +1869,232 @@ relation.command("rm").argument("[issue]").argument("[id-or-issue]").option("--j
     return relationRm(ctx, issue, idOrIssue);
   });
 });
+var plan = program.command("plan").description("plans: a whole graph of issues created in one request, then released and held");
+plan.command("create").description("create a plan from a JSON or YAML file (the API's request body); it starts held").option("--file <path>", 'the plan: .json is JSON, anything else YAML ("-" for stdin)').option("--team <key>", "team of the root and of people's steps (or HARNESS_TEAM)").option("--idempotency-key <key>", "reuse the same key when deliberately retrying this create").option("--json", "emit JSON").action(async (opts) => {
+  await withConfig(opts.json === true, true, (ctx) => {
+    if (opts.file === void 0) {
+      throw new UsageError("usage: harness plan create --file <plan.json|plan.yaml> [--team <key>]");
+    }
+    const team2 = requiredTeam(ctx, opts.team);
+    validateIdempotencyKey(opts.idempotencyKey);
+    return planCreate(ctx, readPlanFile(opts.file), { ...opts, team: team2 });
+  });
+});
+plan.command("show").description("a plan's status, budgets, revision, steps, edges and wait conditions").argument("[id]").option("--json", "emit JSON").action(async (id, opts) => {
+  await withConfig(opts.json === true, false, (ctx) => {
+    if (id === void 0) throw new UsageError("usage: harness plan show <plan-id>");
+    return planShow(ctx, id);
+  });
+});
+plan.command("edit").description("change step executors and keys, and budgets, from a JSON or YAML file").argument("[id]").option("--file <path>", 'the edit: .json is JSON, anything else YAML ("-" for stdin)').option("--json", "emit JSON").action(async (id, opts) => {
+  await withConfig(opts.json === true, true, (ctx) => {
+    if (id === void 0 || opts.file === void 0) {
+      throw new UsageError("usage: harness plan edit <plan-id> --file <edits.json|edits.yaml>");
+    }
+    requirePlanId(id);
+    return planEdit(ctx, id, readPlanFile(opts.file));
+  });
+});
+plan.command("release").description("release a plan as yourself: freeze its next revision and let its ready steps run").argument("[id]").option("--collaborator <who>", "a person of this organization (id or email) for the plan room (repeatable)", collect, []).option("--retry-budget <n>", "retries per failed Operator step", integer).option("--spend-budget-cents <n>", "the plan's spend budget; needed to release Operator steps", integer).option("--json", "emit JSON").action(
+  async (id, opts) => {
+    await withConfig(opts.json === true, true, (ctx) => {
+      if (id === void 0) throw new UsageError("usage: harness plan release <plan-id>");
+      return planRelease(ctx, id, { ...opts, collaborators: opts.collaborator });
+    });
+  }
+);
+plan.command("hold").description("pause every step of a plan until it is released again").argument("[id]").option("--json", "emit JSON").action(async (id, opts) => {
+  await withConfig(opts.json === true, true, (ctx) => {
+    if (id === void 0) throw new UsageError("usage: harness plan hold <plan-id>");
+    return planHold(ctx, id);
+  });
+});
+var gate = program.command("gate").description("manual wait conditions: gate satisfy|unsatisfy <issue> <gate>");
+for (const [verb, satisfied] of [
+  ["satisfy", true],
+  ["unsatisfy", false]
+]) {
+  gate.command(verb).description(`${satisfied ? "tick" : "untick"} a gate on an issue, by its key, label or condition id`).argument("[issue]").argument("[gate]").option("--json", "emit JSON").action(async (issue, gateName, opts) => {
+    await withConfig(opts.json === true, true, (ctx) => {
+      if (issue === void 0 || gateName === void 0) {
+        throw new UsageError(`usage: harness gate ${verb} <issue> <gate-key-label-or-id>`);
+      }
+      return gateSet(ctx, issue, gateName, satisfied);
+    });
+  });
+}
+program.command("conditions").description("an issue's wait conditions; with an outside expert's pxc_ credential, the gates they own on it").argument("[issue]").option("--json", "emit JSON").action(async (issue, opts) => {
+  await withConfig(opts.json === true, false, (ctx) => {
+    if (issue === void 0) throw new UsageError("usage: harness conditions <issue>");
+    return conditionList(ctx, issue);
+  });
+});
+program.command("assignments").description("an outside expert's steps and the gates they own on them (pxc_ credentials only)").option("--json", "emit JSON").action(async (opts) => {
+  await withConfig(opts.json === true, false, (ctx) => assignments(ctx));
+});
+var NO_OBJECTIVE_TEXT = "By reference only: never the objective's text, which the API does not return because it can quote what Operator read; the workbench link opens it. Approval happens in the app.";
+program.command("jobs").description("Operator jobs you see in the workbench, newest first").option(
+  "--status <states>",
+  `comma-separated job states (${JOB_STATES.join(", ")}) or open | waiting | done`
+).option("--mine", "only jobs you own").option(`--limit <n>`, `jobs per page (default 20, max ${JOBS_MAX_LIMIT})`, integer).option("--all", `follow every page (up to ${JOBS_MAX_PAGES})`).option("--json", "emit JSON").addHelpText("after", `
+${NO_OBJECTIVE_TEXT}
+`).action(async (opts) => {
+  requireJobsArgs(opts);
+  await withConfig(opts.json === true, false, (ctx) => jobsList(ctx, opts));
+});
+program.command("job").description("one Operator job: status, plan, progress, window, spend, approval link, effects, artifacts, people").argument("[id]").option("--changes", "instead, its change set by reference (never values or targets), with the approval link").option("--people", "instead, who is on it by name: requester, execution principal, owner, approvers, collaborators").option("--json", "emit JSON").addHelpText("after", `
+${NO_OBJECTIVE_TEXT}
+`).action(async (id, opts) => {
+  if (id === void 0) throw new UsageError("usage: harness job <job-id> [--changes] [--people]");
+  requireJobId(id);
+  await withConfig(
+    opts.json === true,
+    false,
+    (ctx) => jobShow(ctx, id, { changes: opts.changes, people: opts.people })
+  );
+});
+program.command("watch").description("follow an Operator job until it completes, fails, or waits for a person").argument("[id]").option("--after <seq>", "start after this event sequence (default 0: the whole history)", integer).option("--through-waits", "keep following while a person has to act, instead of stopping").option("--json", "emit one JSON document when the watch ends").addHelpText(
+  "after",
+  `
+Polls the job's events every 2 s, and every 10 s while the job is paused or
+a person has to act. A person has to act exactly when the job's waiting_on is
+set: an approval, a person, reconciliation, verification or delivery. A job
+paused with nothing for a person to do resumes by itself, so watch follows it.
+It only reads: approval happens in the app, and the approval link is printed.
+A failed poll is retried 3 times (1, 2, 4 s, or the server's Retry-After).
+
+Exit codes:
+  0    the job completed (or stdout's reader went away, e.g. | head)
+  ${EXIT_WAITING_FOR_PERSON}    a person has to act (not with --through-waits); the link is printed
+  ${EXIT_JOB_ENDED}    the job failed or was cancelled
+  ${EXIT_INTERRUPTED}  interrupted with Ctrl-C; stderr says where to resume (--after)
+  1, 3 as for every command: an API error, or the API unreachable after the retries;
+       stderr says where to resume, and --json still prints the events read so far
+  2    a usage error
+`
+).action(async (id, opts) => {
+  if (id === void 0) throw new UsageError("usage: harness watch <job-id>");
+  requireJobId(id);
+  const json2 = opts.json === true;
+  await withConfig(
+    json2,
+    false,
+    (ctx) => jobWatch(ctx, id, {
+      after: opts.after,
+      throughWaits: opts.throughWaits === true,
+      collectEvents: json2,
+      onLine: json2 ? void 0 : (line) => process.stdout.write(line),
+      signal: watchStopSignal()
+    })
+  );
+});
+var NOT_RETRIED = `
+Not idempotent, so it is never retried, not even after a timeout or a server
+error. When a failure leaves the outcome unknown it says so and exits 1:
+check \`job <id>\` before trying again. Exit 3 means the request never
+reached the server, so nothing changed. It answers the job as \`job\` shows
+it. Approving stays in the app.
+`;
+program.command("steer").description("post an instruction to an Operator job, as Steer does in the app; earlier approvals stop applying").argument("[id]").argument("[instruction...]").option("--instruction-file <path>", 'read the instruction from a file ("-" for stdin)').option("--json", "emit JSON").addHelpText(
+  "after",
+  `
+Posts the instruction in the job's room, attributed to you, wherever the app
+offers Steer; the job's owner and collaborators may steer. Work it changes
+needs a fresh approval, and a running job stops its current run to take it.
+At most ${STEER_MAX_CHARACTERS} characters once trimmed.
+
+Quote the instruction: unquoted words that look like options (--json, --help)
+are read as options, not text. Put -- before an instruction that starts with
+"-", or pass it with --instruction-file, which takes any text as it is.
+${NOT_RETRIED}`
+).action(async (id, words, opts) => {
+  if (id === void 0 || words.length === 0 && opts.instructionFile === void 0) {
+    throw new UsageError(
+      "usage: harness steer <job-id> <instruction> | harness steer <job-id> --instruction-file <path>"
+    );
+  }
+  requireJobId(id);
+  const instruction = instructionFrom(words, opts.instructionFile);
+  await withConfig(opts.json === true, true, (ctx) => jobSteer(ctx, id, instruction));
+});
+program.command("cancel").description("cancel an Operator job; committed effects stay committed, and their counts are printed").argument("[id]").option("--json", "emit JSON").addHelpText(
+  "after",
+  `
+Ends the job, as Cancel does in the app; only its execution principal may.
+Staged effects that never ran count as unknown.
+${NOT_RETRIED}`
+).action(async (id, opts) => {
+  if (id === void 0) throw new UsageError("usage: harness cancel <job-id>");
+  requireJobId(id);
+  await withConfig(opts.json === true, true, (ctx) => jobCancel(ctx, id));
+});
+program.command("pause").description("pause a running Operator job for a person, keeping its active-time budget").argument("[id]").option("--json", "emit JSON").addHelpText(
+  "after",
+  `
+Holds the job, as Pause does in the app; only its execution principal may.
+Continue it to run again.
+${NOT_RETRIED}`
+).action(async (id, opts) => {
+  if (id === void 0) throw new UsageError("usage: harness pause <job-id>");
+  requireJobId(id);
+  await withConfig(opts.json === true, true, (ctx) => jobPause(ctx, id));
+});
+var NOT_IDEMPOTENT = "Not idempotent: it is sent once and never retried, not after a timeout or a 5xx either. Exit 3 means the request never reached the server, so nothing changed. When it may have, the outcome is unknown: it exits 1 and says so. Then check";
+function once(flag) {
+  return (value, previous) => {
+    if (previous !== void 0) throw new InvalidArgumentError(`${flag} given twice \u2014 pass it once`);
+    return value;
+  };
+}
+program.command("continue").description(
+  "open a new audited window for an Operator job that ran out of time or waits on a person, as Continue does in the app"
+).argument("[id]").option("--json", "emit JSON").addHelpText(
+  "after",
+  `
+Only the job's execution principal, the person it runs as, may continue it. ${NOT_IDEMPOTENT} \`job <id>\` before continuing it again.
+`
+).action(async (id, opts) => {
+  if (id === void 0) throw new UsageError("usage: harness continue <job-id>");
+  requireJobId(id);
+  await withConfig(opts.json === true, true, (ctx) => jobContinue(ctx, id));
+});
+var procedure = program.command("procedure").description("saved Operator procedures: procedure save|show|run");
+procedure.command("save").description("save a completed, verified job as a procedure, as Save procedure does in the app (its owner only)").argument("[job-id]").option("--name <name>", "the procedure's name (trimmed, at most 200 characters)", once("--name")).option("--json", "emit JSON").addHelpText(
+  "after",
+  `
+Saving again saves another procedure. ${NOT_IDEMPOTENT} the job's procedures (\`job <id>\`) before saving it again.
+`
+).action(async (jobId, opts) => {
+  if (jobId === void 0) throw new UsageError('usage: harness procedure save <job-id> --name "\u2026"');
+  requireJobId(jobId);
+  const name = requireProcedureName(opts.name);
+  await withConfig(opts.json === true, true, (ctx) => procedureSave(ctx, jobId, name));
+});
+procedure.command("show").description("one procedure: its source job, versions (digest, capabilities, actions) and the parameters a run takes").argument("[id]").option("--json", "emit JSON").action(async (id, opts) => {
+  if (id === void 0) throw new UsageError("usage: harness procedure show <procedure-id>");
+  requireProcedureId(id);
+  await withConfig(opts.json === true, false, (ctx) => procedureShow(ctx, id));
+});
+procedure.command("run").description("run a procedure as a new job, with fresh inputs, your current rights and an approval of its own in the app").argument("[id]").option("--version <n>", "the version expected to be current (default: whichever is current)", once("--version")).option("--param <name=value>", "a parameter, as a string; name:=<json> for a JSON value (repeatable)", collect, []).option("--params-file <path>", 'the parameters as one JSON object ("-" for stdin)', once("--params-file")).option("--group <id>", "the contact group to reconcile, when the procedure needs one", once("--group")).option("--source <id>", "the uploaded file to reconcile against, when the procedure needs one", once("--source")).option("--json", "emit JSON").addHelpText(
+  "after",
+  `
+Nothing of the saved job carries over: no grant, approval, delegation, collaborator or read material. Approving happens in the app. ${NOT_IDEMPOTENT} \`jobs\` for the new job before running it again.
+`
+).action(
+  async (id, opts) => {
+    if (id === void 0) {
+      throw new UsageError("usage: harness procedure run <procedure-id> [--version N] [--param name=value]\u2026");
+    }
+    const request = prepareProcedureRun(id, {
+      version: opts.version,
+      param: opts.param,
+      paramsFile: opts.paramsFile,
+      group: opts.group,
+      source: opts.source
+    });
+    await withConfig(opts.json === true, true, (ctx) => startProcedureRun(ctx, request));
+  }
+);
 var commentCommand = program.command("comment").description("comment on an issue").argument("[id]").argument("[text...]").option("--body-file <path>", 'read the comment body from a file ("-" for stdin)').option("--mention <name>", "notify a person (repeatable)", collect, []).option("--json", "emit JSON").action(
   async (id, text, opts) => {
     await withConfig(opts.json === true, true, (ctx) => {
@@ -2093,9 +2374,40 @@ program.command("upload").description("upload an image (25 MB) or H.264 MP4 vide
     return upload(ctx, path);
   });
 });
+var tools = program.command("tools").description(
+  "the capabilities Operator can use now in this organization (switched-off ones never appear); write and send capabilities need approval in the app"
+).option("--domain <domain>", "only this domain (`tools domains` lists them)").option("--cursor <cursor>", "continue from a page's cursor (from the paging notice)").option("--all", "follow every page").option("--json", "emit JSON").action(async (opts) => {
+  requireToolsOpts(opts);
+  await withConfig(opts.json === true, false, (ctx) => toolsList(ctx, opts));
+});
+tools.command("search").description("search what Operator can use now by keyword, best match first").argument("[query...]").option("--domain <domain>", "only this domain").option("--cursor <cursor>", "continue from a page's cursor (from the paging notice)").option("--all", "follow every page").option("--json", "emit JSON").action(async (query, opts) => {
+  const merged = { ...tools.opts(), ...opts };
+  if (query.length === 0) {
+    throw new UsageError("usage: harness tools search <query> [--domain <domain>] [--all]");
+  }
+  requireSearchQuery(query.join(" "));
+  requireToolsOpts(merged);
+  await withConfig(merged.json === true, false, (ctx) => toolsSearch(ctx, query.join(" "), merged));
+});
+tools.command("domains").description("every domain Operator can use capabilities in, with how many").option("--json", "emit JSON").action(async (opts) => {
+  const parent = tools.opts();
+  if (parent.domain !== void 0 || parent.cursor !== void 0 || parent.all === true) {
+    throw new UsageError("usage: harness tools domains [--json] (it takes no --domain, --cursor or --all)");
+  }
+  await withConfig(opts.json === true || parent.json === true, false, (ctx) => toolsDomains(ctx));
+});
+program.command("tool").description("one capability Operator can use, with its whole input schema (or, for a read, its result schema)").argument("[id]").option("--schema <which>", "input (the default) or result, for a read").option("--json", "emit JSON").action(async (id, opts) => {
+  if (id === void 0) throw new UsageError("usage: harness tool <capability-id> [--schema input|result]");
+  requireCapabilityId(id);
+  requireSchemaView(opts.schema);
+  await withConfig(opts.json === true, false, (ctx) => toolShow(ctx, id, opts));
+});
+program.command("skills").description("the organization's skills assigned to Operator: identity and content checksum, never content").option("--json", "emit JSON").action(async (opts) => {
+  await withConfig(opts.json === true, false, (ctx) => skillsList(ctx));
+});
 program.command("mcp").description("run the MCP server over stdio (for agents)").action(async () => {
-  const { startMcpServer } = await import("./server-CYBKYG5E.js");
-  await startMcpServer();
+  const { startMcpServer } = await import("./server-O7CX2ZCC.js");
+  await startMcpServer(invokedAs);
 });
 var keys = program.command("keys").description("the org's provider API keys, handed to tooling without printing them").enablePositionalOptions();
 keys.command("list").description("provider slugs the org has keys for and the env var each maps to \u2014 never the values").option("--json", "emit JSON").action(async (opts) => {
@@ -2155,7 +2467,16 @@ program.command("whoami").description("show the resolved host and credential sou
     return exitWith(2);
   }
   const source = blankToUndefined(process.env["HARNESS_API_TOKEN"]) !== void 0 ? "environment" : "stored login";
-  await finishAuth(await whoami(resolved.config, source), opts.json === true);
+  let result;
+  try {
+    result = await whoami(resolved.config, source);
+  } catch (error) {
+    if (!(error instanceof TransportError)) throw error;
+    process.stderr.write(`harness: cannot reach the API: ${clean(error.message)}
+`);
+    return exitWith(3);
+  }
+  await finishAuth(result, opts.json === true);
 });
 function storedLoginUrl() {
   return readCredentials(defaultCredentialsPath())?.url;
@@ -2183,6 +2504,7 @@ try {
   if (notice !== null) process.stderr.write(notice);
 } catch {
 }
+if (invokedAs === "operator") layoutOperatorHelp(program);
 if (argv.length <= 2) {
   program.outputHelp({ error: true });
   await exitWith(2);