@allocator-one/harness-cli 1.13.0 → 1.14.0

package/dist/{chunk-XFMECLOU.js → chunk-F2YVTB2A.js}

@@ -25,6 +25,12 @@ var TransportError = class extends Error {
     this.name = "TransportError";
   }
 };
+var MalformedResponseError = class extends TransportError {
+  constructor(message) {
+    super(message);
+    this.name = "MalformedResponseError";
+  }
+};
 var UsageError = class extends Error {
   constructor(message) {
     super(message);
@@ -178,10 +184,10 @@ var Client = class {
     try {
       parsed = JSON.parse(text);
     } catch {
-      throw new TransportError(`the API answered with a non-JSON body (HTTP ${response.status})`);
+      throw new MalformedResponseError(`the API answered with a non-JSON body (HTTP ${response.status})`);
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-      throw new TransportError(`the API answered with an invalid JSON envelope (HTTP ${response.status})`);
+      throw new MalformedResponseError(`the API answered with an invalid JSON envelope (HTTP ${response.status})`);
     }
     return parsed;
   }
@@ -230,16 +236,31 @@ function clean(value) {
 function json(term) {
   return JSON.stringify(term) + "\n";
 }
-function issuesTable(issues) {
+var OPERATOR_TEAM_KEY = /^OPERATOR\d*$/;
+var OPERATOR_TEAM_NAME = "Operator";
+var AGENT_MARK = "[agent]";
+var AGENT_LEGEND = `
+${AGENT_MARK} Operator runs this step for its plan; only the plan driver claims it.
+`;
+function isAgentStep(issue) {
+  return OPERATOR_TEAM_KEY.test(str(path(issue, "team", "key"))) && str(path(issue, "team", "name")) === OPERATOR_TEAM_NAME;
+}
+function issuesTable(issues, options = {}) {
   if (issues.length === 0) return "No issues.\n";
-  const rows = issues.map((issue) => [
-    str(issue["identifier"]),
-    str(path(issue, "state", "name")) || "-",
-    str(issue["priority_label"]) || "-",
-    str(path(issue, "assignee", "name")) || "-",
-    truncate(issue["title"])
-  ]);
-  return table(["ID", "STATE", "PRIORITY", "ASSIGNEE", "TITLE"], rows);
+  let marked = false;
+  const rows = issues.map((issue) => {
+    const agentStep = options.markAgentSteps === true && isAgentStep(issue);
+    if (agentStep) marked = true;
+    return [
+      str(issue["identifier"]),
+      str(path(issue, "state", "name")) || "-",
+      str(issue["priority_label"]) || "-",
+      str(path(issue, "assignee", "name")) || "-",
+      agentStep ? truncate(`${AGENT_MARK} ${clean(issue["title"])}`) : truncate(issue["title"])
+    ];
+  });
+  const rendered = table(["ID", "STATE", "PRIORITY", "ASSIGNEE", "TITLE"], rows);
+  return marked ? rendered + AGENT_LEGEND : rendered;
 }
 function issueDetail(issue, images = []) {
   const header = `${str(issue["identifier"])} \xB7 ${clean(issue["title"])}
@@ -251,6 +272,7 @@ function issueDetail(issue, images = []) {
     ["Team", path(issue, "team", "key")],
     ["Labels", labelsLine(issue["labels"])],
     ["Blocked", blockedLine(issue)],
+    ["Waiting", waitingLine(issue)],
     ["Due", issue["due_date"]],
     ["Updated", issue["updated_at"]]
   ];
@@ -266,7 +288,7 @@ function issueDetail(issue, images = []) {
 ${title}:
 ${indent(String(text))}
 `).join("");
-  return header + fieldLines + sectionText + relationsSection(issue["relations"]) + childrenSection(issue["children"]) + commentsSection(issue["comments"]) + imagesSection(images);
+  return header + fieldLines + sectionText + conditionsSection(issue["conditions"]) + relationsSection(issue["relations"]) + childrenSection(issue["children"]) + commentsSection(issue["comments"]) + imagesSection(images);
 }
 function activityEntries(entries) {
   if (entries.length === 0) return "No activity.\n";
@@ -411,6 +433,185 @@ function table(headers, rows) {
     (row) => row.map((cell, column) => padGraphemes(cell, widths[column] ?? 0)).join("  ").replace(/\s+$/, "") + "\n"
   ).join("");
 }
+function records(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter(
+    (entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry)
+  );
+}
+function waitingLine(issue) {
+  if (issue["waiting_on_condition"] !== true) return null;
+  const conditions = records(issue["conditions"]);
+  const open = conditions.filter((condition) => condition["satisfied"] !== true).length;
+  return `yes, on ${open} of ${conditions.length} wait condition${conditions.length === 1 ? "" : "s"}`;
+}
+function conditionsSection(conditions) {
+  const list2 = records(conditions);
+  if (list2.length === 0) return "";
+  return "\nWait conditions:\n" + list2.map((condition) => `  ${conditionLine(condition)}
+`).join("");
+}
+function conditionLine(condition) {
+  const satisfied = condition["satisfied"] === true;
+  let what;
+  switch (condition["kind"]) {
+    case "gate":
+      what = `gate "${clean(condition["label"])}"`;
+      break;
+    case "not_before":
+      what = `not before ${clean(condition["not_before"])}`;
+      break;
+    case "event":
+      what = "system event";
+      break;
+    default:
+      what = clean(condition["kind"]) || "condition";
+  }
+  let when = "";
+  if (satisfied && typeof condition["satisfied_at"] === "string") {
+    const by = clean(path(condition, "satisfied_by", "name"));
+    when = ` (satisfied ${clean(condition["satisfied_at"])}${by === "" ? "" : ` by ${by}`})`;
+  }
+  return `${satisfied ? "[x]" : "[ ]"} ${what}${when} \xB7 ${clean(condition["id"])}`;
+}
+var LIVE_PLAN_STATUSES = ["released", "running", "needs_attention"];
+function planDetail(plan) {
+  const steps = records(plan["steps"]);
+  const fields = [
+    ["Root", planRootLine(plan["root"])],
+    ["Revision", planRevisionLine(plan)],
+    ["Budgets", planBudgetsLine(plan)],
+    ["Estimate", planEstimateLine(plan["estimate"])]
+  ];
+  const fieldLines = fields.filter((field2) => field2[1] !== null).map(([label, value]) => `  ${(label + ":").padEnd(12)}${value}
+`).join("");
+  return `Plan ${clean(plan["id"])} \xB7 ${clean(plan["status"])}
+` + fieldLines + planStepsSection(steps, str(plan["status"])) + planEdgesSection(plan["edges"]) + planConditionsSection(steps) + planHeldSection(plan["held_steps"]);
+}
+function planRootLine(root) {
+  if (typeof root !== "object" || root === null) return null;
+  const record = root;
+  return `${clean(record["identifier"])} \xB7 ${clean(record["title"])}`;
+}
+function planRevisionLine(plan) {
+  const revision = plan["revision"];
+  if (typeof revision !== "object" || revision === null) return "none yet (never released)";
+  const number = clean(revision["number"]);
+  const by = clean(path(plan, "released_by", "name"));
+  const at = clean(plan["released_at"]);
+  if (by === "" && at === "") return number;
+  return `${number} \xB7 released${by === "" ? "" : ` by ${by}`}${at === "" ? "" : ` at ${at}`}`;
+}
+function planBudgetsLine(plan) {
+  const retries = plan["retry_budget"];
+  const retryText = typeof retries === "number" ? `${retries} ${retries === 1 ? "retry" : "retries"} per failed Operator step` : null;
+  const spend = plan["spend_budget_cents"];
+  const spendText = typeof spend === "number" ? `spend budget ${spend} cents` : "no spend budget";
+  return [retryText, spendText].filter((part) => part !== null).join(" \xB7 ");
+}
+function planEstimateLine(estimate) {
+  if (typeof estimate !== "object" || estimate === null) return null;
+  const record = estimate;
+  const ceiling = record["ceiling_cents"];
+  if (typeof ceiling !== "number") return null;
+  const minimum = record["minimum_budget_cents"];
+  return `up to ${ceiling} cents${typeof minimum === "number" ? ` (minimum budget ${minimum} cents)` : ""}`;
+}
+function planStepsSection(steps, planStatus) {
+  if (steps.length === 0) return "";
+  const depths = stepDepths(steps);
+  const rows = steps.map((step) => [
+    "  ".repeat(depths.get(str(step["identifier"])) ?? 0) + str(step["identifier"]),
+    str(step["key"]) || "-",
+    str(step["executor"]) || "-",
+    str(path(step, "state", "name")) || "-",
+    stepStatus(step, planStatus),
+    truncate(step["title"])
+  ]);
+  const rendered = table(["STEP", "KEY", "EXECUTOR", "STATE", "STATUS", "TITLE"], rows);
+  return "\nSteps:\n" + indentLines(rendered);
+}
+function stepDepths(steps) {
+  const parents = new Map(steps.map((step) => [str(step["identifier"]), str(step["parent"])]));
+  const depths = /* @__PURE__ */ new Map();
+  for (const identifier of parents.keys()) {
+    let depth = 0;
+    let parent = parents.get(identifier) ?? "";
+    const seen = /* @__PURE__ */ new Set([identifier]);
+    while (parent !== "" && parents.has(parent) && !seen.has(parent)) {
+      seen.add(parent);
+      depth += 1;
+      parent = parents.get(parent) ?? "";
+    }
+    depths.set(identifier, depth);
+  }
+  return depths;
+}
+function stepStatus(step, planStatus) {
+  const stateType = path(step, "state", "type");
+  if (step["archived"] === true) return "archived";
+  if (stateType === "completed") return "done";
+  if (stateType === "canceled") return "cancelled";
+  if (step["container"] === true) return "container";
+  if (step["ready"] === true) return "ready";
+  if (step["held"] === true) return "held";
+  if (step["in_revision"] === false && LIVE_PLAN_STATUSES.includes(planStatus)) return "not in revision";
+  if (records(step["conditions"]).some((condition) => condition["satisfied"] !== true)) return "waiting";
+  return "-";
+}
+function planEdgesSection(edges) {
+  const list2 = records(edges);
+  if (list2.length === 0) return "";
+  return "\nEdges (blocker \u2192 blocked):\n" + list2.map((edge) => `  ${clean(edge["from"])} \u2192 ${clean(edge["to"])}
+`).join("");
+}
+function planConditionsSection(steps) {
+  const lines = steps.flatMap(
+    (step) => records(step["conditions"]).map((condition) => [clean(step["identifier"]), conditionLine(condition)])
+  );
+  if (lines.length === 0) return "";
+  const width = Math.max(...lines.map(([identifier]) => graphemeLength(identifier)));
+  return "\nWait conditions:\n" + lines.map(([identifier, line]) => `  ${padGraphemes(identifier, width)}  ${line}
+`).join("");
+}
+function planHeldSection(heldSteps) {
+  if (!Array.isArray(heldSteps) || heldSteps.length === 0) return "";
+  return `
+Held by an edit until the plan is released again: ${heldSteps.map((step) => clean(step)).join(", ")}
+`;
+}
+function indentLines(text) {
+  return text.split("\n").map((line) => line === "" ? line : "  " + line).join("\n");
+}
+function errorDetails(body) {
+  return changesetDetails(body["details"]) + violationDetails(body["violations"]);
+}
+function changesetDetails(details) {
+  if (typeof details !== "object" || details === null || Array.isArray(details)) return "";
+  return Object.entries(details).map(([field2, messages]) => {
+    const text = Array.isArray(messages) ? messages.map(String).join("; ") : String(messages);
+    return `
+  ${clean(field2)}: ${clean(text)}`;
+  }).join("");
+}
+function violationDetails(violations) {
+  return records(violations).map((violation) => {
+    const code = clean(violation["code"]);
+    const message = clean(violation["message"]) || code || "invalid";
+    return `
+  ${violationSubject(violation)}: ${message}${code === "" ? "" : ` [${code}]`}`;
+  }).join("");
+}
+function violationSubject(violation) {
+  const key = typeof violation["key"] === "string" ? clean(violation["key"]) : null;
+  const index = typeof violation["index"] === "number" ? `steps[${violation["index"]}]` : null;
+  const issue = typeof violation["issue"] === "string" ? clean(violation["issue"]) : null;
+  if (key !== null) {
+    const where = index ?? issue;
+    return where === null ? `step "${key}"` : `step "${key}" (${where})`;
+  }
+  return issue ?? index ?? "plan";
+}
 function relationsSection(relations) {
   if (!Array.isArray(relations) || relations.length === 0) return "";
   const lines = relations.map((relation) => `  ${str(relation["direction"]).padEnd(14)}${str(relation["other_issue"])}
@@ -447,10 +648,30 @@ function labelsLine(labels) {
 }
 function blockedLine(issue) {
   if (issue["blocked"] === true && Array.isArray(issue["blocked_by"])) {
-    return `yes, by ${issue["blocked_by"].map(String).join(", ")}`;
+    const notes = blockerNotes(issue["blockers"]);
+    const blockers = issue["blocked_by"].map((blocker) => {
+      const identifier = String(blocker);
+      const note = notes.get(identifier);
+      return note === void 0 ? identifier : `${identifier} (${note})`;
+    });
+    return `yes, by ${blockers.join(", ")}`;
   }
   return null;
 }
+function blockerNotes(blockers) {
+  const notes = /* @__PURE__ */ new Map();
+  if (!Array.isArray(blockers)) return notes;
+  for (const blocker of blockers) {
+    if (typeof blocker !== "object" || blocker === null) continue;
+    const record = blocker;
+    if (typeof record["identifier"] !== "string") continue;
+    const reasons = [];
+    if (record["state_type"] === "canceled") reasons.push("cancelled");
+    if (record["archived"] === true) reasons.push("archived");
+    if (reasons.length > 0) notes.set(record["identifier"], reasons.join(", "));
+  }
+  return notes;
+}
 function indent(text) {
   return cleanMultiline(text).split("\n").map((line) => "  " + line).join("\n");
 }
@@ -608,8 +829,8 @@ function write(path2, bytes) {
 }
 
 // src/core/pagination.ts
-function notices(meta, requestedPageSize, records) {
-  return capNotice(meta, requestedPageSize) + truncationNotice(meta, records);
+function notices(meta, requestedPageSize, records2) {
+  return capNotice(meta, requestedPageSize) + truncationNotice(meta, records2);
 }
 function capNotice(meta, requestedPageSize) {
   const served = meta?.page_size;
@@ -619,12 +840,12 @@ function capNotice(meta, requestedPageSize) {
   }
   return "";
 }
-function truncationNotice(meta, records) {
+function truncationNotice(meta, records2) {
   const total = meta?.total;
   const page = meta?.page;
   const pages = meta?.total_pages;
   if (typeof total !== "number" || typeof page !== "number" || typeof pages !== "number") return "";
-  const shown = records.length;
+  const shown = records2.length;
   if (shown < total) {
     return `harness: showing ${shown} of ${total} (page ${page} of ${pages}) \u2014 pass --all for the rest, or --page to step through.
 `;
@@ -635,20 +856,20 @@ async function fetchEveryPage(fetchPage) {
   const first = await fetchPage(1);
   const totalPages = pageCount(first.meta);
   if (totalPages === null) return first.data;
-  let records = first.data;
+  let records2 = first.data;
   for (let page = 2; page <= totalPages; page++) {
     const body = await fetchPage(page);
-    records = dedupe([...records, ...body.data]);
+    records2 = dedupe([...records2, ...body.data]);
   }
-  return records;
+  return records2;
 }
 function pageCount(meta) {
   const total = meta?.total_pages;
   return typeof total === "number" && total > 0 ? total : null;
 }
-function dedupe(records) {
+function dedupe(records2) {
   const seen = /* @__PURE__ */ new Set();
-  return records.filter((record) => {
+  return records2.filter((record) => {
     const id = record["id"];
     const key = id === void 0 || id === null ? `struct:${stableKey(record)}` : `id:${stableKey(id)}`;
     if (seen.has(key)) return false;
@@ -671,7 +892,6 @@ var STATUS_STATE_TYPES = {
   in_progress: "started",
   closed: "completed,canceled"
 };
-var READY_CLAIM_ATTEMPTS = 10;
 var MAX_IDEMPOTENCY_KEY_BYTES = 200;
 var IDEMPOTENCY_KEY_FORMAT = /^[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?(?![\s\S])/;
 var IDENTIFIER_FORMAT = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
@@ -686,22 +906,72 @@ function requireIdentifiers(identifiers) {
   }
 }
 async function ready(ctx, opts) {
+  if (opts.claim === true) return claimNext(ctx, opts);
   const params = { ...listParams(ctx, opts), ready: true };
-  const { records, notice } = await fetchIssues(ctx, params, opts);
+  const { records: records2, notice } = await fetchIssues(ctx, params, opts);
   const rank = (issue) => PRIORITY_RANK[issue["priority"]] ?? 4;
-  const sorted = [...records].sort((a, b) => rank(a) - rank(b));
-  if (opts.claim === true) return claimFirst(ctx, sorted);
-  return { json: sorted, human: issuesTable(sorted), notice };
+  const sorted = markAgentSteps([...records2].sort((a, b) => rank(a) - rank(b)));
+  return { json: sorted, human: issuesTable(sorted, { markAgentSteps: true }), notice };
+}
+function markAgentSteps(issues) {
+  return issues.map((issue) => ({ ...issue, agent_step: isAgentStep(issue) }));
+}
+function requireReadyClaimArgs(opts) {
+  const paging = [
+    opts.all === true ? "--all" : null,
+    opts.limit !== void 0 ? "--limit" : null,
+    opts.page !== void 0 ? "--page" : null
+  ].filter((flag) => flag !== null);
+  if (paging.length === 0) return;
+  const last = paging.pop();
+  const flags = paging.length === 0 ? last : `${paging.join(", ")} or ${last}`;
+  throw new UsageError(
+    `--claim cannot be combined with ${flags}: the server picks from the team's whole ready queue, so there are no pages to choose from`
+  );
+}
+async function claimNext(ctx, opts) {
+  requireReadyClaimArgs(opts);
+  const team = requiredTeam(ctx, opts.team);
+  const check = `check \`harness list --team ${team} --assignee me --status in_progress\``;
+  const unreadable = (why) => new CommandError(`The claim-next response ${why}, so an issue may have been claimed \u2014 ${check}.`);
+  let body;
+  try {
+    body = await ctx.client.post(`/api/v1/teams/${team}/issues/claim-next`);
+  } catch (error) {
+    if (error instanceof MalformedResponseError) throw unreadable(`could not be read (${error.message})`);
+    if (error instanceof TransportError) {
+      throw new TransportError(
+        `${error.message} \u2014 if the request reached the server, an issue may have been claimed; ${check} before claiming again`
+      );
+    }
+    throw error;
+  }
+  if (body.data === null) {
+    return { json: null, human: `Nothing to claim: team ${team} has no unassigned ready issues.
+` };
+  }
+  const claimed = body.data;
+  if (!isIssueRecord(claimed)) throw unreadable("carried neither an issue nor null");
+  return {
+    json: claimed,
+    human: `Claimed ${str2(claimed["identifier"])}: ${clean(claimed["title"])}
+`
+  };
+}
+function isIssueRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const identifier = value["identifier"];
+  return typeof identifier === "string" && identifier !== "";
 }
 async function blocked(ctx, opts) {
   const params = { ...listParams(ctx, opts), blocked: true };
-  const { records, notice } = await fetchIssues(ctx, params, opts);
-  return { json: records, human: issuesTable(records), notice };
+  const { records: records2, notice } = await fetchIssues(ctx, params, opts);
+  return { json: records2, human: issuesTable(records2), notice };
 }
 async function list(ctx, opts) {
   const params = listParams(ctx, opts);
-  const { records, notice } = await fetchIssues(ctx, params, opts);
-  return { json: records, human: issuesTable(records), notice };
+  const { records: records2, notice } = await fetchIssues(ctx, params, opts);
+  return { json: records2, human: issuesTable(records2), notice };
 }
 async function search(ctx, queryWords, opts) {
   if (queryWords.length === 0) throw new UsageError("usage: harness search <query>");
@@ -792,9 +1062,9 @@ async function stats2(ctx) {
 }
 async function prime(ctx) {
   const statsBody = await ctx.client.get("/api/v1/stats");
-  const readyBody = await ctx.client.get("/api/v1/issues", { ready: true, page_size: 10 });
-  const json2 = { stats: statsBody.data, ready: readyBody.data };
-  const human = "# Harness workflow context\n\n" + stats(statsBody.data) + "\nReady to work:\n" + issuesTable(readyBody.data) + `
+  const ready2 = markAgentSteps(await mostImportantReady(ctx));
+  const json2 = { stats: statsBody.data, ready: ready2 };
+  const human = "# Harness workflow context\n\n" + stats(statsBody.data) + "\nReady to work:\n" + issuesTable(ready2, { markAgentSteps: true }) + `
 Workflow: harness ready \u2192 harness update <id> --claim \u2192 work \u2192
 harness close <id> --reason "Implemented in <commit-hash>" (response
 lists newly unblocked issues \u2014 surface them).
@@ -804,6 +1074,14 @@ Before reporting done: close the issues you finished.
 `;
   return { json: json2, human };
 }
+async function mostImportantReady(ctx) {
+  try {
+    return (await ctx.client.get("/api/v1/issues/next", { limit: 10 })).data;
+  } catch (error) {
+    if (!(error instanceof HttpError) || error.status !== 404) throw error;
+    return (await ctx.client.get("/api/v1/issues", { ready: true, page_size: 10 })).data;
+  }
+}
 async function version(config) {
   let server;
   if (config === null || config.baseUrl === "") {
@@ -873,8 +1151,12 @@ async function update(ctx, identifier, opts) {
   let issue = labelPlan?.issue ?? null;
   let wrote = false;
   if (opts.claim === true) {
-    const body = await ctx.client.post(`/api/v1/issues/${identifier}/claim`);
-    issue = body.data;
+    try {
+      const body = await ctx.client.post(`/api/v1/issues/${identifier}/claim`);
+      issue = body.data;
+    } catch (error) {
+      throw explainClaimRefusal(error, identifier);
+    }
     wrote = true;
   }
   let patch = {};
@@ -919,6 +1201,19 @@ ${opts.appendNotes}`;
 `;
   return { json: issue, human };
 }
+var CLAIM_REFUSAL_HINTS = {
+  // The edit holds a released step, so the plan needs releasing again before
+  // the step is claimable.
+  agent_step: () => "Operator runs it for its plan; to do it yourself, set its executor to none (harness plan edit <plan-id>) and release the plan again",
+  waiting_on_condition: (identifier) => `harness show ${identifier} lists what it waits on; tick a gate with harness gate satisfy ${identifier} <gate>`
+};
+function explainClaimRefusal(error, identifier) {
+  if (!(error instanceof HttpError) || error.status !== 409) return error;
+  const reason = error.body["reason"];
+  const hint = typeof reason === "string" && Object.hasOwn(CLAIM_REFUSAL_HINTS, reason) ? CLAIM_REFUSAL_HINTS[reason](identifier) : void 0;
+  if (hint === void 0) return error;
+  return new HttpError(error.status, `${error.message} \u2014 ${hint}`, error.body, error.retryAfter);
+}
 function requireCloseArgs(identifiers, opts) {
   if (identifiers.length === 0) {
     throw new UsageError(
@@ -960,7 +1255,9 @@ async function close(ctx, identifiers, opts) {
       identifier: result.identifier,
       closed: true,
       ...opts.duplicateOf === void 0 ? {} : { duplicate_of: opts.duplicateOf },
-      unblocked: result.response["unblocked"] ?? null
+      unblocked: result.response["unblocked"] ?? null,
+      // Passed through as sent: older servers omit it, and so does this.
+      ..."still_blocking" in result.response ? { still_blocking: result.response["still_blocking"] } : {}
     } : { identifier: result.identifier, closed: false, error: errorText(result.error) }
   );
   const partial = results.some((result) => !result.ok);
@@ -971,11 +1268,15 @@ function closeLine(result, duplicateOf) {
 `;
   const closure = duplicateOf === void 0 ? `Closed ${result.identifier}` : `Closed ${result.identifier} as duplicate of ${duplicateOf}`;
   const unblocked = result.response["unblocked"];
-  if (Array.isArray(unblocked) && unblocked.length > 0) {
-    return `${closure} \u2014 unblocked: ${unblocked.map(String).join(", ")}
+  const line = Array.isArray(unblocked) && unblocked.length > 0 ? `${closure} \u2014 unblocked: ${unblocked.map((identifier) => clean(identifier)).join(", ")}
+` : `${closure}
 `;
-  }
-  return `${closure}
+  return line + stillBlockingLine(result.response["still_blocking"]);
+}
+function stillBlockingLine(stillBlocking) {
+  if (!Array.isArray(stillBlocking) || stillBlocking.length === 0) return "";
+  const identifiers = stillBlocking.map((identifier) => clean(identifier)).join(", ");
+  return `  Still blocking: ${identifiers} (a cancelled issue still blocks its dependents)
 `;
 }
 async function archive(ctx, identifiers, opts) {
@@ -1210,23 +1511,6 @@ function posixDetail(error) {
   if (code === "EACCES") return "permission denied";
   return error instanceof Error ? error.message : String(error);
 }
-async function claimFirst(ctx, issues) {
-  for (const issue of issues.slice(0, READY_CLAIM_ATTEMPTS)) {
-    try {
-      const body = await ctx.client.post(`/api/v1/issues/${str2(issue["identifier"])}/claim`);
-      const claimed = body.data;
-      return {
-        json: claimed,
-        human: `Claimed ${str2(claimed["identifier"])}: ${clean(claimed["title"])}
-`
-      };
-    } catch (error) {
-      if (error instanceof HttpError && error.status === 409) continue;
-      throw error;
-    }
-  }
-  throw new CommandError("No claimable ready issues.");
-}
 async function setState(ctx, identifier, stateName2) {
   const showBody = await ctx.client.get(`/api/v1/issues/${identifier}`);
   const teamKey = str2((showBody.data["team"] ?? {})["key"]);
@@ -1390,15 +1674,15 @@ async function fetchIssues(ctx, params, opts) {
     throw new UsageError("--all reads every page from the first \u2014 pass --all or --page, not both");
   }
   if (opts.all === true) {
-    const records2 = await fetchEveryPage(
+    const records3 = await fetchEveryPage(
       (page) => ctx.client.get("/api/v1/issues", { ...params, page })
     );
-    return { records: records2, notice: "" };
+    return { records: records3, notice: "" };
   }
   const body = await ctx.client.get("/api/v1/issues", params);
-  const records = body.data;
+  const records2 = body.data;
   const requested = typeof params["page_size"] === "number" ? params["page_size"] : void 0;
-  return { records, notice: notices(body.meta, requested, records) };
+  return { records: records2, notice: notices(body.meta, requested, records2) };
 }
 function listParams(ctx, opts) {
   if (opts.type !== void 0 && opts.label !== void 0) {
@@ -1524,8 +1808,8 @@ async function paginatedRead(ctx, path2, params, opts) {
     throw new UsageError("--all reads every page from the first \u2014 pass --all or --page, not both");
   }
   if (opts.all === true) {
-    const records = await fetchEveryPage((page) => ctx.client.get(path2, { ...params, page }));
-    return { records, notice: "" };
+    const records2 = await fetchEveryPage((page) => ctx.client.get(path2, { ...params, page }));
+    return { records: records2, notice: "" };
   }
   const body = await ctx.client.get(path2, params);
   const requested = typeof params["page_size"] === "number" ? params["page_size"] : void 0;
@@ -1535,10 +1819,10 @@ async function projectList(ctx, opts) {
   let params = { page_size: opts.limit ?? 50, page: opts.page ?? 1 };
   if (opts.search !== void 0) params = { ...params, search: opts.search };
   if (opts.state !== void 0) params = { ...params, state: opts.state };
-  const { records, notice } = await paginatedRead(ctx, "/api/v1/projects", params, opts);
-  const human = records.length === 0 ? "No projects.\n" : table(
+  const { records: records2, notice } = await paginatedRead(ctx, "/api/v1/projects", params, opts);
+  const human = records2.length === 0 ? "No projects.\n" : table(
     ["ID", "STATE", "LEAD", "TARGET", "NAME"],
-    records.map((project) => [
+    records2.map((project) => [
       str3(project["id"]),
       str3(project["state"]) || "-",
       str3(field(project, "lead", "name")) || "-",
@@ -1546,7 +1830,7 @@ async function projectList(ctx, opts) {
       str3(project["name"])
     ])
   );
-  return { json: records, human, notice };
+  return { json: records2, human, notice };
 }
 async function projectShow(ctx, id) {
   requireSafeId("project", id);
@@ -1637,12 +1921,12 @@ async function milestoneCreate(ctx, opts) {
 async function docList(ctx, opts) {
   let params = { page_size: opts.limit ?? 50, page: opts.page ?? 1 };
   if (opts.search !== void 0) params = { ...params, search: opts.search };
-  const { records, notice } = await paginatedRead(ctx, "/api/v1/documents", params, opts);
-  const human = records.length === 0 ? "No documents.\n" : table(
+  const { records: records2, notice } = await paginatedRead(ctx, "/api/v1/documents", params, opts);
+  const human = records2.length === 0 ? "No documents.\n" : table(
     ["ID", "UPDATED", "TITLE"],
-    records.map((doc) => [str3(doc["id"]), str3(doc["updated_at"]) || "-", str3(doc["title"])])
+    records2.map((doc) => [str3(doc["id"]), str3(doc["updated_at"]) || "-", str3(doc["title"])])
   );
-  return { json: records, human, notice };
+  return { json: records2, human, notice };
 }
 async function docShow(ctx, id) {
   requireSafeId("document", id);
@@ -1931,8 +2215,315 @@ function indent2(text) {
   return cleanMultiline(text).split("\n").map((line) => "  " + line).join("\n");
 }
 
+// src/core/textinput.ts
+import { readFileSync as readFileSync3, statSync as statSync3 } from "fs";
+import { isatty } from "tty";
+var STDIN_PATH = "-";
+var MAX_TEXT_BYTES = 1e6;
+var TEXT_LIMIT = { bytes: MAX_TEXT_BYTES, why: "that is not prose; check the path" };
+var DOCUMENT_LIMIT = { bytes: 8e6, why: "larger than the API accepts in one request" };
+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, `--${flagOf(name)}-file`);
+    toRead.push({ name, file });
+  }
+  for (const { name, file } of [...toRead].sort(byStdinLast)) {
+    resolved[name] = stripOneTrailingNewline(readTextFile(file, `--${flagOf(name)}-file`));
+  }
+  return resolved;
+}
+function readFileOption(flag, path2) {
+  if (path2 === STDIN_PATH) {
+    if (isatty(0)) {
+      throw new UsageError(`${flag} - reads stdin, but stdin is a terminal \u2014 pipe something in or pass a path`);
+    }
+  } else {
+    checkReadable(path2, flag, DOCUMENT_LIMIT);
+  }
+  return readTextFile(path2, flag, DOCUMENT_LIMIT);
+}
+function readTextFile(path2, option, limit = TEXT_LIMIT) {
+  if (path2 === STDIN_PATH) {
+    let piped;
+    try {
+      piped = readFileSync3(0);
+    } catch (error) {
+      throw new UsageError(`${option} -: cannot read stdin (${describe(error)})`);
+    }
+    if (piped.length > limit.bytes) {
+      throw new UsageError(oversize(`${option} -`, limit));
+    }
+    return decodeUtf8(piped, `${option} -`);
+  }
+  const flag = `${option} ${path2}`;
+  let bytes;
+  try {
+    bytes = readFileSync3(path2);
+  } catch (error) {
+    throw new UsageError(`${flag}: ${describe(error)}`);
+  }
+  if (bytes.length > limit.bytes) throw new UsageError(oversize(flag, limit));
+  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, limit) {
+  return `${what}: over ${limit.bytes / 1e6} MB \u2014 ${limit.why}`;
+}
+function checkReadable(path2, option, limit = TEXT_LIMIT) {
+  const flag = `${option} ${path2}`;
+  let stats3;
+  try {
+    stats3 = statSync3(path2);
+  } catch (error) {
+    throw new UsageError(`${flag}: ${describe(error)}`);
+  }
+  if (!stats3.isFile()) {
+    throw new UsageError(
+      `${flag}: ${stats3.isDirectory() ? "is a directory" : "not a regular file"}`
+    );
+  }
+  if (stats3.size > limit.bytes) throw new UsageError(oversize(flag, limit));
+}
+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/commands/plans.ts
+import { extname as extname2 } from "path";
+import { parseDocument } from "yaml";
+var PLAN_EXECUTORS = ["none", "operator"];
+var CONDITION_KINDS = ["not_before", "gate", "event"];
+function parsePlanDocument(text, source) {
+  const parsed = extname2(source).toLowerCase() === ".json" ? parseJson(text, source) : parseYamlDocument(text, source);
+  if (!isRecord(parsed)) {
+    throw new UsageError(`${source}: a plan file holds one object (a mapping), not a list or a scalar`);
+  }
+  return parsed;
+}
+function parseJson(text, source) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new UsageError(`${source}: not valid JSON (${firstLine(error)})`);
+  }
+}
+function parseYamlDocument(text, source) {
+  const document = parseDocument(text, { resolveKnownTags: false });
+  const problem = document.errors[0] ?? document.warnings[0];
+  if (problem !== void 0) throw new UsageError(`${source}: not valid YAML (${firstLine(problem)})`);
+  let value;
+  try {
+    value = document.toJS();
+  } catch (error) {
+    throw new UsageError(`${source}: not valid YAML (${firstLine(error)})`);
+  }
+  if (!jsonSafe(value)) {
+    throw new UsageError(`${source}: holds a value JSON cannot carry (.inf or .nan) \u2014 write a number or a string`);
+  }
+  return value;
+}
+function jsonSafe(value) {
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every(jsonSafe);
+  if (typeof value === "object" && value !== null) return Object.values(value).every(jsonSafe);
+  return true;
+}
+function firstLine(error) {
+  return (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? "";
+}
+function readPlanFile(path2, flag = "--file") {
+  return parsePlanDocument(readFileOption(flag, path2), path2);
+}
+async function planCreate(ctx, plan, opts) {
+  requireDocument(plan, "a plan is one object: the root's fields and its steps");
+  const team = requiredTeam(ctx, opts.team);
+  validateIdempotencyKey(opts.idempotencyKey);
+  let body;
+  try {
+    body = await ctx.client.post(`/api/v1/teams/${team}/plans`, plan, { idempotencyKey: opts.idempotencyKey });
+  } catch (error) {
+    throw explainMissing(error, `no team ${team} here, or this Harness server has no plan API yet`);
+  }
+  const created = body.data;
+  const id = str4(created["id"]);
+  return {
+    json: created,
+    human: `Created plan ${clean(id)} (${clean(created["status"]) || "held"})
+
+` + planDetail(created) + `
+Nothing runs until it is released: harness plan release ${clean(id)}
+`
+  };
+}
+async function planShow(ctx, id) {
+  requirePlanId(id);
+  const plan = await planRequest(id, () => ctx.client.get(`/api/v1/plans/${id}`));
+  return { json: plan, human: planDetail(plan) };
+}
+async function planEdit(ctx, id, edits) {
+  requirePlanId(id);
+  requireDocument(edits, "a plan edit is one object: steps to change and budgets");
+  const plan = await planRequest(id, () => ctx.client.patch(`/api/v1/plans/${id}`, edits));
+  const held = Array.isArray(plan["held_steps"]) && plan["held_steps"].length > 0;
+  return {
+    json: plan,
+    human: `Updated plan ${clean(id)}
+
+` + planDetail(plan) + (held ? `
+Release it again to run the held steps: harness plan release ${clean(id)}
+` : "")
+  };
+}
+async function planRelease(ctx, id, opts) {
+  requirePlanId(id);
+  const body = {};
+  if (opts.collaborators !== void 0 && opts.collaborators.length > 0) body["collaborators"] = opts.collaborators;
+  if (opts.retryBudget !== void 0) body["retry_budget"] = opts.retryBudget;
+  if (opts.spendBudgetCents !== void 0) body["spend_budget_cents"] = opts.spendBudgetCents;
+  const plan = await planRequest(id, () => ctx.client.post(`/api/v1/plans/${id}/release`, body));
+  const revision = plan["revision"] ?? {};
+  const ready2 = Array.isArray(plan["steps"]) ? plan["steps"].filter((step) => isRecord(step) && step["ready"] === true).length : 0;
+  return {
+    json: plan,
+    human: `Released plan ${clean(id)} as revision ${clean(revision["number"]) || "?"}: ${ready2} ${ready2 === 1 ? "step" : "steps"} ready now
+`
+  };
+}
+async function planHold(ctx, id) {
+  requirePlanId(id);
+  const plan = await planRequest(id, () => ctx.client.post(`/api/v1/plans/${id}/hold`));
+  return {
+    json: plan,
+    human: `Held plan ${clean(id)}: none of its steps is ready until it is released again
+`
+  };
+}
+async function gateSet(ctx, issue, gate, satisfied) {
+  requireIdentifiers([issue]);
+  const wanted = gate.trim();
+  if (wanted === "") throw new UsageError("name the gate by its label or its condition id");
+  let conditions;
+  try {
+    conditions = (await ctx.client.get(`/api/v1/issues/${issue}/conditions`)).data;
+  } catch (error) {
+    throw explainMissing(error, `no issue ${issue} here, or this Harness server has no wait conditions yet`);
+  }
+  if (!Array.isArray(conditions)) throw new CommandError("The conditions response carried no list.");
+  const list2 = conditions.filter(isRecord);
+  const target = findGate(list2, issue, wanted);
+  const id = str4(target["id"]);
+  const body = await ctx.client.put(`/api/v1/issues/${issue}/conditions/${id}/satisfaction`, {
+    satisfied
+  });
+  const others = list2.filter((condition) => condition["id"] !== id && condition["satisfied"] !== true).length;
+  let tail = "";
+  if (satisfied) {
+    tail = others > 0 ? ` \u2014 it still waits on ${others} other condition${others === 1 ? "" : "s"}` : " \u2014 no other wait condition holds it";
+  }
+  return {
+    json: body.data,
+    human: `${satisfied ? "Satisfied" : "Un-satisfied"} gate "${clean(target["label"])}" on ${issue}${tail}
+`
+  };
+}
+function requirePlanId(id) {
+  if (!isUuid(id)) throw new UsageError(`not a plan id: ${id} (expected the plan's UUID)`);
+}
+function requireDocument(value, what) {
+  if (!isRecord(value)) throw new UsageError(what);
+}
+async function planRequest(id, send) {
+  try {
+    return (await send()).data;
+  } catch (error) {
+    throw explainMissing(error, `no plan ${id} in this organization, or this Harness server has no plan API yet`);
+  }
+}
+function explainMissing(error, why) {
+  if (!(error instanceof HttpError) || error.status !== 404) return error;
+  return new HttpError(404, `${error.message} \u2014 ${why}`, error.body, error.retryAfter);
+}
+function findGate(conditions, issue, wanted) {
+  const gates = conditions.filter((condition) => condition["kind"] === "gate");
+  const label = (condition) => str4(condition["label"]).trim();
+  if (isUuid(wanted) && !gates.some((condition) => label(condition) === wanted)) {
+    const byId = conditions.find((condition) => str4(condition["id"]).toLowerCase() === wanted.toLowerCase());
+    if (byId === void 0) throw new CommandError(`No condition ${wanted} on ${issue}.`);
+    if (byId["kind"] !== "gate") {
+      throw new CommandError(
+        `condition ${wanted} on ${issue} is a ${clean(byId["kind"])} condition \u2014 only a gate is satisfied by hand`
+      );
+    }
+    return byId;
+  }
+  let matches = gates.filter((condition) => label(condition) === wanted);
+  if (matches.length === 0) {
+    matches = gates.filter((condition) => label(condition).toLowerCase() === wanted.toLowerCase());
+  }
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) {
+    const ids = matches.map((condition) => clean(condition["id"])).join(", ");
+    throw new CommandError(`several gates on ${issue} match "${wanted}" \u2014 pass the condition id: ${ids}`);
+  }
+  if (gates.length === 0) throw new CommandError(`No gate on ${issue} matches "${wanted}" \u2014 it has no gates`);
+  const labels = gates.map((condition) => `"${clean(label(condition))}"`).join(", ");
+  throw new CommandError(`No gate on ${issue} matches "${wanted}". Its gates: ${labels}`);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function str4(value) {
+  return value === null || value === void 0 ? "" : String(value);
+}
+
 // src/core/credentials.ts
-import { chmodSync as chmodSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, renameSync as renameSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { chmodSync as chmodSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync4, renameSync as renameSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
 import { homedir } from "os";
 import { dirname as dirname2, isAbsolute, join as join2 } from "path";
 function defaultCredentialsPath(env = process.env) {
@@ -1942,7 +2533,7 @@ function defaultCredentialsPath(env = process.env) {
 }
 function readCredentials(path2) {
   try {
-    const parsed = JSON.parse(readFileSync3(path2, "utf8"));
+    const parsed = JSON.parse(readFileSync4(path2, "utf8"));
     if (typeof parsed === "object" && parsed !== null) {
       const { url, token } = parsed;
       if (typeof url === "string" && typeof token === "string") return { url, token };
@@ -1969,7 +2560,7 @@ function deleteCredentials(path2) {
 }
 
 // src/core/repo-config.ts
-import { existsSync, mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync, mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
 import { homedir as homedir2 } from "os";
 import { dirname as dirname3, isAbsolute as isAbsolute2, join as join3, parse } from "path";
 var CONFIG_RELATIVE_PATH = join3(".harness-cli", "config.json");
@@ -1988,7 +2579,7 @@ function findRepoConfig(startDir = process.cwd()) {
 function readRepoConfig(path2) {
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync4(path2, "utf8"));
+    parsed = JSON.parse(readFileSync5(path2, "utf8"));
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
     return { config: null, warnings: [`harness: ignoring malformed ${path2} (${detail})`] };
@@ -2017,7 +2608,7 @@ function trustedHostsPath(env = process.env) {
 }
 function readTrustedHosts(env) {
   try {
-    const parsed = JSON.parse(readFileSync4(trustedHostsPath(env), "utf8"));
+    const parsed = JSON.parse(readFileSync5(trustedHostsPath(env), "utf8"));
     if (typeof parsed === "object" && parsed !== null && Array.isArray(parsed["hosts"])) {
       return parsed["hosts"].filter(
         (host) => typeof host === "string"
@@ -2180,10 +2771,12 @@ export {
   Client,
   clean,
   json,
+  errorDetails,
   MAX_IDEMPOTENCY_KEY_BYTES,
   IDEMPOTENCY_KEY_FORMAT,
   requireIdentifiers,
   ready,
+  requireReadyClaimArgs,
   blocked,
   list,
   search,
@@ -2194,6 +2787,7 @@ export {
   prime,
   version,
   create,
+  validateIdempotencyKey,
   update,
   requireCloseArgs,
   close,
@@ -2211,6 +2805,7 @@ export {
   deleteComment,
   requireCommentId,
   attachImage,
+  requiredTeam,
   projectList,
   projectShow,
   projectCreate,
@@ -2243,6 +2838,17 @@ export {
   memberAdd,
   memberSetRole,
   upload,
+  resolveTextSources,
+  PLAN_EXECUTORS,
+  CONDITION_KINDS,
+  readPlanFile,
+  planCreate,
+  planShow,
+  planEdit,
+  planRelease,
+  planHold,
+  gateSet,
+  requirePlanId,
   defaultCredentialsPath,
   readCredentials,
   writeCredentials,