@allocator-one/harness-cli 1.12.1 → 1.14.0

package/dist/cli.js

@@ -30,7 +30,9 @@ import {
   docShow,
   docUpdate,
   editComment,
+  errorDetails,
   findRepoConfig,
+  gateSet,
   isHostTrusted,
   json,
   labelCreate,
@@ -48,21 +50,32 @@ import {
   memberSetRole,
   milestoneCreate,
   milestoneList,
+  planCreate,
+  planEdit,
+  planHold,
+  planRelease,
+  planShow,
   prime,
   projectCreate,
   projectList,
   projectShow,
   projectUpdate,
   readCredentials,
+  readPlanFile,
   ready,
   relationAdd,
   relationList,
   relationRm,
   relationUpdate,
+  requireCloseArgs,
   requireCommentId,
   requireIdentifiers,
+  requirePlanId,
+  requireReadyClaimArgs,
+  requiredTeam,
   resolveCacheHome,
   resolveConfig,
+  resolveTextSources,
   search,
   show,
   stateAdd,
@@ -79,10 +92,11 @@ import {
   upload,
   userList,
   validateBaseUrl,
+  validateIdempotencyKey,
   version,
   workflowStates,
   writeCredentials
-} from "./chunk-VOH6BBJD.js";
+} from "./chunk-F2YVTB2A.js";
 
 // src/cli.ts
 import { createInterface as createInterface2 } from "readline";
@@ -808,113 +822,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]) {
@@ -933,11 +840,11 @@ 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";
@@ -980,7 +887,7 @@ function findPackageRoot(from) {
 }
 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;
@@ -991,7 +898,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"];
@@ -1056,7 +963,7 @@ function stampPath(env = process.env) {
 }
 function readStamp(env = process.env) {
   try {
-    const parsed = JSON.parse(readFileSync2(stampPath(env), "utf8"));
+    const parsed = JSON.parse(readFileSync(stampPath(env), "utf8"));
     if (typeof parsed !== "object" || parsed === null) return null;
     const record = parsed;
     const checkedAt = record["checkedAt"];
@@ -1361,8 +1268,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;
@@ -1556,17 +1463,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,
@@ -1676,7 +1577,7 @@ function requireNonBlankTitle(text, titleFile) {
 program.command("create").description("create an issue atomically after resolving requested labels").option("--title <text>", "issue title (required)").option("--description <text>", "problem statement").option("--design <text>", "design notes").option("--notes <text>", "working notes").option("--acceptance <text>", "acceptance criteria").option("--title-file <path>", 'read the title from a file ("-" for stdin)').option("--description-file <path>", 'read the description from a file ("-" for stdin)').option("--design-file <path>", 'read the design notes from a file ("-" for stdin)').option("--notes-file <path>", 'read the notes from a file ("-" for stdin)').option("--acceptance-file <path>", 'read the acceptance criteria from a file ("-" for stdin)').option(
   "--type <type>",
   "task | bug | feature | epic (applied as a type/ label)"
-).option("--priority <name>", "urgent | high | medium | low | none").option("--due-date <date>", "YYYY-MM-DD").option("--parent <id>", "parent epic").option("--assignee <who>", "me, a user id, an email, or a full name").option("--team <key>", "team key (or HARNESS_TEAM)").option(
+).option("--priority <name>", "urgent | high | medium | low | none").option("--due-date <date>", "YYYY-MM-DD").option("--parent <id>", "parent epic").option("--assignee <who>", "me, a user id, an email, or a full name").option("--team <key>", "team key (or HARNESS_TEAM)").option("--idempotency-key <key>", "reuse the same key when deliberately retrying this create").option(
   "--label <name>",
   "resolve team-first, then workspace; create missing workspace labels before the issue (repeatable)",
   collect,
@@ -1726,15 +1627,15 @@ program.command("update").description("update an issue; --claim takes it atomica
     });
   }
 );
-program.command("close").description("close issues; the response lists newly unblocked issues").argument("[ids...]").option("--reason <text>", "why it is done (e.g. the commit hash)").option("--reason-file <path>", 'read the reason from a file ("-" for stdin)').option("--cancel", "close as canceled instead of completed").option("--json", "emit JSON").action(
+program.command("close").description("close issues; the response lists newly unblocked issues").argument("[ids...]").option("--reason <text>", "why it is done (e.g. the commit hash)").option("--reason-file <path>", 'read the reason from a file ("-" for stdin)').option("--cancel", "close as canceled instead of completed").option("--duplicate-of <id>", "close one issue as a duplicate of the canonical issue").option("--json", "emit JSON").action(
   async (ids, opts) => {
+    if (ids.length === 0) {
+      throw new UsageError(
+        "usage: harness close <id> [<id>\u2026] [--reason <text> | --reason-file <path>] [--cancel | --duplicate-of <id>]"
+      );
+    }
+    requireCloseArgs(ids, opts);
     await withConfig(opts.json === true, true, (ctx) => {
-      if (ids.length === 0) {
-        throw new UsageError(
-          "usage: harness close <id> [<id>\u2026] [--reason <text> | --reason-file <path>] [--cancel]"
-        );
-      }
-      requireIdentifiers2(ids);
       const text = resolveTextSources([
         { name: "reason", inline: opts.reason, file: opts.reasonFile }
       ]);
@@ -1813,6 +1714,60 @@ 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 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-label-or-id>`);
+      }
+      return gateSet(ctx, issue, gateName, satisfied);
+    });
+  });
+}
 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,7 +2048,7 @@ program.command("upload").description("upload an image (25 MB) or H.264 MP4 vide
   });
 });
 program.command("mcp").description("run the MCP server over stdio (for agents)").action(async () => {
-  const { startMcpServer } = await import("./server-FNNMISOZ.js");
+  const { startMcpServer } = await import("./server-75QJASTY.js");
   await startMcpServer();
 });
 var keys = program.command("keys").description("the org's provider API keys, handed to tooling without printing them").enablePositionalOptions();

package/dist/{server-FNNMISOZ.js → server-75QJASTY.js}

@@ -2,8 +2,12 @@
 import {
   ACTIVITY_MAX_LIMIT,
   CLI_VERSION,
+  CONDITION_KINDS,
   Client,
   HttpError,
+  IDEMPOTENCY_KEY_FORMAT,
+  MAX_IDEMPOTENCY_KEY_BYTES,
+  PLAN_EXECUTORS,
   RELATION_CREATE_TYPES,
   RELATION_UPDATE_TYPES,
   TransportError,
@@ -22,6 +26,8 @@ import {
   docShow,
   docUpdate,
   editComment,
+  errorDetails,
+  gateSet,
   labelCreate,
   labelDelete,
   labelList,
@@ -36,6 +42,11 @@ import {
   memberSetRole,
   milestoneCreate,
   milestoneList,
+  planCreate,
+  planEdit,
+  planHold,
+  planRelease,
+  planShow,
   projectCreate,
   projectList,
   projectShow,
@@ -61,7 +72,7 @@ import {
   upload,
   userList,
   workflowStates
-} from "./chunk-VOH6BBJD.js";
+} from "./chunk-F2YVTB2A.js";
 
 // src/mcp/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -97,7 +108,9 @@ async function run(work) {
     return { content };
   } catch (error) {
     if (error instanceof NeedsLoginError) return toolError(error.message);
-    if (error instanceof HttpError) return toolError(`${error.message} (HTTP ${error.status})`);
+    if (error instanceof HttpError) {
+      return toolError(`${error.message} (HTTP ${error.status})${errorDetails(error.body)}`);
+    }
     if (error instanceof TransportError) return toolError(`cannot reach the API: ${error.message}`);
     if (error instanceof Error) return toolError(error.message);
     throw error;
@@ -111,11 +124,55 @@ var page = {
 var identifier = z.string().describe("issue identifier, e.g. IO-123");
 var commentId = z.string().uuid().describe("comment UUID from issue_show or comment_list");
 var dateField = z.string().optional().describe('YYYY-MM-DD; "" clears the date');
+var planCondition = z.object({
+  kind: z.enum(CONDITION_KINDS),
+  not_before: z.string().optional().describe("not_before: an ISO 8601 UTC instant"),
+  label: z.string().optional().describe("gate: what a person ticks, e.g. Finance sign-off"),
+  event: z.string().optional().describe("event: deal_stage_changed, opportunity_stage_changed, form_submitted or investment_executed"),
+  subject_id: z.string().optional().describe("event: the record the event is about (one you can read)"),
+  target_id: z.string().optional().describe("event: the stage or status a stage change must reach")
+}).passthrough();
+var planIssueFields = {
+  title: z.string(),
+  description: z.string().optional().describe("an Operator step's description is its instruction (required for one)"),
+  design: z.string().optional(),
+  notes: z.string().optional(),
+  acceptance_criteria: z.string().optional(),
+  priority: z.number().int().optional().describe("0 none, 1 urgent, 2 high, 3 medium, 4 low"),
+  estimate: z.number().optional(),
+  due_date: z.string().optional().describe("YYYY-MM-DD"),
+  assignee: z.string().optional().describe("email or user id; never on an Operator step"),
+  label_ids: z.array(z.string()).optional()
+};
+var planStep = z.object({
+  ...planIssueFields,
+  key: z.string().describe("unique in the plan; other steps refer to this step by it"),
+  parent: z.string().optional().describe("key of the step that contains this one; the root when absent"),
+  blocked_by: z.array(z.string()).optional().describe("keys of the steps this one waits for"),
+  executor: z.enum(PLAN_EXECUTORS).optional().describe("none (a person, the default) or operator"),
+  team: z.string().optional().describe("team key for a person's step; Operator steps go to the Operator team"),
+  conditions: z.array(planCondition).optional().describe("wait conditions: all must hold before the step is ready")
+}).passthrough();
+var planDocument = z.object({
+  ...planIssueFields,
+  parent: z.string().optional().describe("an existing issue to file the root under, e.g. IO-12"),
+  retry_budget: z.number().int().min(0).optional().describe("retries per failed Operator step (default 2)"),
+  spend_budget_cents: z.number().int().min(0).nullable().optional().describe("needed to release a plan with Operator steps"),
+  steps: z.array(planStep).min(1).describe("at most 99 steps besides the root")
+}).passthrough();
+var planId = z.string().uuid().describe("plan UUID, from plan_create");
+var planStepEdit = z.object({
+  step: z.string().optional().describe("the step's key; give this or issue"),
+  issue: z.string().optional().describe("the step's issue identifier; give this or step"),
+  executor: z.enum(PLAN_EXECUTORS).optional().describe("none hands the step to a person"),
+  key: z.string().nullable().optional().describe("the step's new key")
+}).passthrough();
+var idempotencyKey = z.string().min(1).max(MAX_IDEMPOTENCY_KEY_BYTES).regex(IDEMPOTENCY_KEY_FORMAT, "must use printable ASCII without leading or trailing spaces");
 var TOOLS = [
   // ── Issues ──
   {
     name: "issue_list",
-    description: "List issues with filters. ready=true \u2192 unblocked open issues; blocked=true \u2192 issues waiting on a blocker.",
+    description: "List issues with filters. ready=true \u2192 unblocked open issues, each with agent_step (true when it is filed in the Operator team, where plan steps Operator runs live: only the plan driver claims those, and a claim refusal is the authority); blocked=true \u2192 issues waiting on a blocker.",
     readOnly: true,
     shape: {
       ...page,
@@ -158,7 +215,7 @@ var TOOLS = [
   },
   {
     name: "issue_show",
-    description: "Full issue detail: fields, relations, children, comments. images=true downloads attached images to the local cache and includes their paths as local_images.",
+    description: "Full issue detail: fields, relations, children, comments. blockers gives each unresolved blocker's state_type and archived flag: only a completed blocker resolves, so a cancelled or archived one still blocks. waiting_on_condition and conditions say which wait conditions (not_before, gate, event) still hold it; tick a gate with gate_set. images=true downloads attached images to the local cache and includes their paths as local_images.",
     readOnly: true,
     shape: { id: identifier, images: z.boolean().optional() },
     handler: (ctx, args) => show(ctx, args["id"], { images: args["images"] === true })
@@ -190,13 +247,15 @@ var TOOLS = [
       due_date: dateField,
       parent: z.string().optional(),
       assignee: z.string().optional(),
-      labels: z.array(z.string()).optional()
+      labels: z.array(z.string()).optional(),
+      idempotency_key: idempotencyKey.optional().describe("reuse the same printable-ASCII key when deliberately retrying this create")
     },
     handler: (ctx, args) => create(ctx, {
       ...args,
       acceptance: args["acceptance_criteria"],
       dueDate: args["due_date"],
-      label: args["labels"]
+      label: args["labels"],
+      idempotencyKey: args["idempotency_key"]
     })
   },
   {
@@ -230,21 +289,26 @@ var TOOLS = [
   },
   {
     name: "issue_claim",
-    description: "Atomically claim an issue: assigns it and moves it to the team's first started state. A conflict means someone else holds it.",
+    description: "Atomically claim an issue: assigns it and moves it to the team's first started state. A conflict names its reason: someone else holds it, or it is not claimable (e.g. agent_step, waiting_on_condition).",
     readOnly: false,
     shape: { id: identifier },
     handler: (ctx, args) => update(ctx, args["id"], { claim: true })
   },
   {
     name: "issue_close",
-    description: "Close issues. The result lists newly unblocked issues \u2014 surface them.",
+    description: "Close issues. Set duplicate_of for one source issue to close it as a duplicate; it cannot be combined with cancel. The result lists newly unblocked issues \u2014 surface them. still_blocking lists the dependents a cancelled or duplicate-closed issue still blocks: only completing releases them.",
     readOnly: false,
     shape: {
       ids: z.array(identifier).min(1),
       reason: z.string().optional().describe("why it is done, e.g. the commit hash"),
-      cancel: z.boolean().optional().describe("close as canceled instead of completed")
+      cancel: z.boolean().optional().describe("close as canceled instead of completed; incompatible with duplicate_of"),
+      duplicate_of: identifier.optional().describe("canonical issue; requires exactly one source id and is incompatible with cancel")
     },
-    handler: (ctx, args) => close(ctx, args["ids"], args)
+    handler: (ctx, args) => close(ctx, args["ids"], {
+      reason: args["reason"],
+      cancel: args["cancel"],
+      duplicateOf: args["duplicate_of"]
+    })
   },
   {
     name: "issue_comment",
@@ -656,6 +720,74 @@ var TOOLS = [
     shape: {},
     handler: (ctx) => stats(ctx)
   },
+  // ── Plans and gates ──
+  {
+    name: "plan_create",
+    description: "Create a plan: a root issue and up to 99 steps, created in one transaction or not at all, and held until a person releases it (plan_release). Steps refer to each other by key: parent (containment) and blocked_by (dependencies). executor operator files a step in the organization's Operator team, where only the plan driver claims it; a person's step goes to its team (or the plan's). conditions are wait conditions (not_before, gate, event). An invalid plan writes nothing and the error lists every violation by step key. Reuse idempotency_key when retrying.",
+    readOnly: false,
+    shape: {
+      team: z.string().optional().describe("team key for the root and people's steps; defaults to HARNESS_TEAM"),
+      plan: planDocument.describe("the root's fields plus steps"),
+      idempotency_key: idempotencyKey.optional().describe("reuse the same printable-ASCII key when deliberately retrying this create")
+    },
+    handler: (ctx, args) => planCreate(ctx, args["plan"], { team: args["team"], idempotencyKey: args["idempotency_key"] })
+  },
+  {
+    name: "plan_show",
+    description: "A plan's status, budgets, current revision and spend estimate, and its whole tree root first: each step's key, executor, parent, state, ready flag, held flag (edited since release), in_revision and wait conditions, plus the blocks edges between steps.",
+    readOnly: true,
+    shape: { id: planId },
+    handler: (ctx, args) => planShow(ctx, args["id"])
+  },
+  {
+    name: "plan_edit",
+    description: "Change step executors and keys (each step named by its key or issue identifier) and the plan's budgets. Editing a released step holds it until the plan is released again; a budget edit needs the plan held. Descriptions, parents and edges are edited with issue_update and relation_add/relation_rm; conditions are set at plan_create, and gate_set ticks a gate.",
+    readOnly: false,
+    shape: {
+      id: planId,
+      steps: z.array(planStepEdit).optional(),
+      retry_budget: z.number().int().min(0).optional(),
+      spend_budget_cents: z.number().int().min(0).nullable().optional().describe("null clears the budget")
+    },
+    handler: (ctx, args) => {
+      const { id, ...edits } = args;
+      return planEdit(ctx, id, edits);
+    }
+  },
+  {
+    name: "plan_release",
+    description: "Release a held plan (or one that needs attention) as the caller: freezes its next revision and lets its ready steps run. A plan with Operator steps needs a spend budget and the caller's right to run Operator; collaborators join its plan room.",
+    readOnly: false,
+    shape: {
+      id: planId,
+      collaborators: z.array(z.string()).max(20).optional().describe("people of this organization, by id or email"),
+      retry_budget: z.number().int().min(0).optional(),
+      spend_budget_cents: z.number().int().min(0).nullable().optional().describe("null clears the budget")
+    },
+    handler: (ctx, args) => planRelease(ctx, args["id"], {
+      collaborators: args["collaborators"],
+      retryBudget: args["retry_budget"],
+      spendBudgetCents: args["spend_budget_cents"]
+    })
+  },
+  {
+    name: "plan_hold",
+    description: "Pause every step of a plan: none is ready until it is released again.",
+    readOnly: false,
+    shape: { id: planId },
+    handler: (ctx, args) => planHold(ctx, args["id"])
+  },
+  {
+    name: "gate_set",
+    description: "Satisfy (satisfied true) or un-satisfy (false) a gate wait condition on an issue, found by its label or condition id (issue_show lists conditions). Needs staff standing in the organization.",
+    readOnly: false,
+    shape: {
+      issue: identifier,
+      gate: z.string().describe("the gate's label, or its condition id"),
+      satisfied: z.boolean()
+    },
+    handler: (ctx, args) => gateSet(ctx, args["issue"], args["gate"], args["satisfied"])
+  },
   // ── Uploads ──
   {
     name: "upload",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allocator-one/harness-cli",
-  "version": "1.12.1",
+  "version": "1.14.0",
   "description": "CLI and MCP server for Harness, allocator.one's issue tracker",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "commander": "^14.0.0",
+    "yaml": "^2.9.1",
     "zod": "^3.25.76"
   },
   "devDependencies": {