@allocator-one/harness-cli 1.15.1 → 1.16.0

package/README.md

@@ -196,7 +196,13 @@ wait conditions, `Waiting:` says how many still hold it, and a
 `Wait conditions:` section lists each one (`[ ] gate "Finance sign-off" · <id>`,
 `[ ] gate "Compliance sign-off" [compliance] owned by Compliance officer (role:compliance_officer) · <id>`,
 `[x] not before … (satisfied …)`, `system event`) with the key and id
-`harness gate satisfy` takes.
+`harness gate satisfy` takes. An issue that belongs to a plan gets a
+`Plan:` line naming the plan by its root identifier, which the `plan`
+commands take, then its status, the revision it runs, and whether that
+revision lists the issue (`Plan: FR-1 · released · revision 8 · not in revision`,
+with `Operator step` for a step Operator runs). `--json` carries the same as
+`plan` (`{id, root, status, held, revision, in_revision, executor}`, or
+`null`).
 `harness activity <id>` prints the issue's activity timeline: comments,
 creation, state and assignee changes, wait-condition events
 (`Ada satisfied the gate "Finance sign-off"`), and field changes
@@ -239,12 +245,18 @@ harness create --title "Fix login redirect" --type bug --priority high \
 
 - `--claim`: atomic. It assigns you and moves the issue to the team's first
   started state. A conflict (exit `1`, HTTP 409) names its reason: someone
-  else holds the issue, or it is not claimable yet. Two reasons come with a
-  next step: `agent_step` (Operator runs it; to do it yourself, set its
-  executor to `none` with `harness plan edit <plan-id>` and release the plan
-  again) and `waiting_on_condition` (`harness show` lists what it waits on;
-  tick a gate with `harness gate satisfy`). It cannot be combined with
-  `--assignee`.
+  else holds the issue, or it is not claimable yet. Some reasons come with a
+  next step. `agent_step`: a person can't claim an Operator step; to do it
+  yourself, set its executor to `none` with `harness plan edit <plan>` and
+  release the plan again. `plan_not_released`, `not_in_plan_revision` and
+  `edited_since_release`: when the server names the one plan governing the
+  issue as the one to release, the error ends with the command
+  (`run harness plan release FR-1`). When several plans govern it, the
+  server names none as the one to release, and the error names the nearest
+  to look at instead (`harness plan show FR-1`). A completed plan, or a
+  server that does not name the plan, gets no such hint. `waiting_on_condition`:
+  `harness show` lists what it waits on; tick a gate with
+  `harness gate satisfy`. It cannot be combined with `--assignee`.
 - `--state <name-or-type>`: moves the issue to the workflow state whose name
   or type matches.
 - `--title`, `--description`, `--design`, `--acceptance`, `--priority`,
@@ -355,12 +367,33 @@ nothing runs until a person releases one.
 
 ```sh
 harness plan create --file plan.yaml --team IO --idempotency-key q3-report
-harness plan show <plan-id>
-harness plan release <plan-id> --collaborator grace@example.com
+harness plan list --team IO                   # the team's plans, by root
+harness plan show IO-120                      # by its root issue, or its id
+harness plan release IO-120 --collaborator grace@example.com
 harness gate satisfy IO-121 "Finance sign-off"
 harness gate satisfy IO-121 compliance        # by the gate's key
 ```
 
+**Finding a plan.** Every plan command takes the plan's id or its root
+issue's identifier (`FR-1`, in any casing). A step's identifier does not
+open its plan: `harness show <issue>` names the plan an issue belongs to by
+its root. `harness plan list` lists a team's plans, newest first, with
+their root, status, whether they are held, the revision they run (`-`
+before the first release) and their title:
+
+```text
+ROOT    STATUS    HELD  REVISION  TITLE
+FR-1    released  no    8         Format radar
+FR-200  held      yes   -         Next quarter
+```
+
+It takes `--team` (or `HARNESS_TEAM` or the repo config), `--status`
+(`held`, `released`, `running`, `completed` or `needs_attention`) and
+`--limit` (default 50, at most 100). There are no pages: when a list comes
+back full, a stderr notice says older plans may exist. `--json` is the
+server's list unchanged, each plan with its `id`, `root`, `title`,
+`status`, `held`, `revision`, `released_at` and `inserted_at`.
+
 **The plan file** is the API's request body, as JSON (`.json`) or YAML
 (anything else, and stdin with `--file -`). YAML is read as YAML 1.2 and
 held to what JSON can carry: dates stay strings, and a duplicate key, an
@@ -415,7 +448,10 @@ steps:
   email). Only the owner can tick an owned gate. You can't name yourself as
   an owner, and that includes a role you hold. `owner: null` or no owner
   leaves the gate unowned.
-- A plan has at most 100 steps, its root included.
+- A plan has at most the organization's max plan steps, its root included:
+  1,000 unless a Harness admin changed it in Harness settings → Plans, and
+  never more than 2,000. Separately, it has at most 100 Operator steps,
+  the fixed limit of the delegated grant Operator runs them under.
 - `--team` (or `HARNESS_TEAM` or the repo config) is the root's team and the
   default team for people's steps. `--idempotency-key` works as it does for
   `create`: if a create times out, run it again with the same key to get
@@ -431,6 +467,18 @@ harness: The plan is not valid; nothing was changed (HTTP 422)
   plan: A plan with Operator steps needs a positive spend budget [spend_budget_required]
 ```
 
+A plan over a step cap gets `too_many_steps`, once for each cap it is
+over, and the line says which cap it is and whether anyone can raise it
+(on create the root has no identifier yet, so the line starts `plan:`):
+
+```text
+  FR-1: the plan has 1203 steps, above this organization's max plan steps (1000): a Harness admin can raise "Max plan steps" in Harness settings → Plans (max_plan_steps, up to 2000) [too_many_steps]
+  FR-1: the plan has 103 Operator steps, above the fixed limit of 100: Operator's delegated grant caps a plan's agent steps, and no setting raises it — hand some to people (executor none) or split the plan [too_many_steps]
+```
+
+The same applies to `plan edit` and `plan release`, which check the caps
+again, and to the MCP tools' error text.
+
 A gate's owner is checked the same way. The owner violations are
 `invalid_owner`, `unknown_role`, `unknown_owner`, `owner_is_member`,
 `owner_is_actor` (you named yourself), `owner_not_allowed` (an owner on a
@@ -438,10 +486,11 @@ condition that is not a gate), `expert_owner_requires_plan`, and
 `duplicate_gate_key`. A `gate:` that conflicts with the condition's `kind`
 or `key` is `invalid_condition`.
 
-**Show.** `harness plan show <plan-id>` prints the plan's status, budgets,
+**Show.** `harness plan show <plan>` prints the plan's status, budgets,
 revision, and spend estimate, then every step in tree order (indented by
 depth) with its key, executor, state, and status. The status is `ready`,
-`held` (edited since the release), `not in revision` (added after it),
+`held` (an Operator step changed since the release, which waits for the
+next one; a person's changed step stays `ready`), `not in revision` (added after it),
 `waiting` (on a wait condition), `container`, `done`, `cancelled`,
 `archived`, or `-`. The edges and each step's wait conditions come after
 the steps. Each gate shows its key and owner. A `Waiting for:` section then
@@ -465,7 +514,7 @@ email), or an outside expert by email (`val@example.com (expert)`).
 `[]` when nobody can tick, `null` for an unowned gate or when the holders
 are not known).
 
-**Edit.** `harness plan edit <plan-id> --file edits.yaml` changes step
+**Edit.** `harness plan edit <plan> --file edits.yaml` changes step
 executors and keys, naming each step by its `step` key or `issue`
 identifier, and the budgets (`retry_budget`, `spend_budget_cents`):
 
@@ -475,33 +524,38 @@ steps:
     executor: none              # hand the step to a person
 ```
 
-Editing a released step holds it until the plan is released again. A
-budget change needs the plan held first. Descriptions, parents, and edges
+Editing a released Operator step, or handing one to a person, holds it
+until the plan is released again. A person's step stays workable, and the
+next release takes the change in; until then the plan lists every changed
+step under `Changed since the release:`. A budget change needs the plan
+held first. Descriptions, parents, and edges
 are edited with the issue commands (`update`, `dep`). Conditions are set
 when the plan is created. Editing them later goes through the API's issue
 condition endpoints, which have no command yet; `gate satisfy` ticks a
 gate.
 
-**Release and hold.** `harness plan release <plan-id>` releases the plan as
-you: it freezes the next revision and lets ready steps run.
+**Release and hold.** `harness plan release <plan>` releases the plan as
+you: it freezes the next revision, which takes in the steps added or edited
+since the last one, and lets ready steps run.
 `--collaborator <id-or-email>` (repeatable) adds people to the plan room
 where its Operator steps run, and `--retry-budget` and
 `--spend-budget-cents` set the budgets. Each Operator step runs as a job
 (`harness jobs` names its plan step), and the changes a job proposes need a
 person's approval in the app, at the job's approval link. The CLI never
-approves. `harness plan hold <plan-id>` pauses every step until the plan is
+approves. `harness plan hold <plan>` pauses every step until the plan is
 released again.
 
 **Gates.** `harness gate satisfy <issue> <gate>` ticks a gate and
 `harness gate unsatisfy <issue> <gate>` unticks it. `<gate>` is the gate's
-key, its label, or its condition id, all shown by `harness show`. None of
-the three outranks the others: when `<gate>` exactly matches more than one
-condition, say one gate's key and another gate's label, the command
-refuses and lists each one's id, key, and label instead of choosing. Pass
-the condition id of the one you mean. Only when nothing matches exactly
-does a label or key match ignoring case, and that too is refused when more
-than one gate matches. Ticking a gate requires staff standing in the
-organization or a place in its plan's room. The server refuses an
+key, its label, or its condition id, all shown by `harness show`. A condition
+UUID writes directly without listing conditions, so a non-staff gate owner can
+reach the server's write authorization. A UUID always addresses that condition,
+even if another gate uses it as its key or label. Keys and labels require the
+staff-only lookup; a denied lookup explains how to use a condition id instead.
+When a name matches multiple gates, the command lists their ids instead of
+choosing. Only when nothing matches exactly does a label or key match ignoring
+case, and that too is refused when more than one gate matches. Ticking a gate
+requires staff standing in the organization or a place in its plan's room. The server refuses an
 Operator-only login (`operator-cli`) here, even for a person in the plan's
 room: it reaches only the Operator commands, `whoami` and `logout`. Only
 the owner can tick an owned gate, and only its owner or Harness staff can
@@ -513,8 +567,10 @@ harness: Cannot satisfy gate "Compliance sign-off" on IO-121: only its owner, Co
 ```
 
 A gate with no owner by then gets the same error without a name. Against
-a server that does not send the owner, the command reads the conditions
-again to find it.
+a server that does not send the owner, a key or label write reads the conditions
+again to find it. A direct condition-id write never lists conditions, including
+on errors, and leaves the owner unnamed if the refusal does not name one.
+Direct writes also make no claim about other conditions still holding the issue.
 
 **Conditions.** `harness conditions <issue>` lists an issue's wait
 conditions, oldest first, one per line as `show` lists them: each one's
@@ -522,7 +578,9 @@ box, what it waits for (a gate's label, key and owner), when and by whom it
 was satisfied, and its id. `--json` is the list as the server sends it.
 
 A server without the plan API answers the plan commands with a 404, and the
-error says that the server may predate plans.
+error says that the server may predate plans. A root identifier that opens
+no plan is the same 404 as an unknown id, and the error says how to find
+the plan an issue belongs to.
 
 ## Outside experts
 
@@ -942,6 +1000,31 @@ Login tokens have it; `aone_` tokens need to be minted with it. There is
 deliberately no MCP tool for keys, because a tool result is text the model
 can read.
 
+## Review gate
+
+A pull request merges only once its enforced Review Council gate, the
+attested review a gate workflow runs for its head, has converged. When that
+gate sits at `unverified`, these commands say why and recover it:
+
+- `harness review status <pr>` prints the enforced and advisory status, the
+  head's gate check, and a failed or timed-out latest attempt with its reason,
+  whether its evidence was recorded, and what comes next. Next is either an
+  automatic retry by Harness or a retry you request. `--json` returns the gate
+  status as the server sends it.
+- `harness review retry <pr> [--reason <text>]` retries the latest attempt of
+  the current head's gate check. It reads the head, the check and the attempt
+  from the gate status, so you name only the pull request, and prints the new
+  attempt (`--json`: `{attempt, outcome}`). Running it again for the same
+  attempt returns the attempt already queued rather than paying for another
+  review run. It needs a login with `reviews:write`. It refuses, saying why,
+  while the attempt is still running, while Harness is retrying it itself, or
+  when the head's advisory review has not converged.
+
+`<pr>` is `owner/repo#<number>`, the pull request URL, or a bare number read
+against `--repo owner/repo` or this checkout's GitHub `origin`. Never dispatch
+the gate workflow by hand instead: a run without a registered attempt cannot
+approve the head.
+
 ## Scripting contract
 
 - **`--json` on every command** except `mcp`. It replaces the human output
@@ -999,7 +1082,7 @@ command instead of the `npx` form. Any other MCP client can use the same command
 { "mcpServers": { "harness": { "command": "npx", "args": ["-y", "@allocator-one/harness-cli", "mcp"] } } }
 ```
 
-The server exposes 72 tools:
+The server exposes 74 tools:
 
 | Area | Tools |
 | --- | --- |
@@ -1011,7 +1094,7 @@ The server exposes 72 tools:
 | Labels | `label_list`, `label_create`, `label_update`, `label_delete` |
 | Teams and states | `team_list`, `team_create`, `team_rename`, `team_set_default`, `workflow_states`, `state_add`, `state_update`, `state_order`, `state_delete` |
 | People | `member_list`, `member_add`, `member_set_role`, `user_list` |
-| Plans and gates | `plan_create`, `plan_show`, `plan_edit`, `plan_release`, `plan_hold`, `gate_set`, `condition_list` |
+| Plans and gates | `plan_list`, `plan_create`, `plan_show`, `plan_edit`, `plan_release`, `plan_hold`, `gate_set`, `condition_list` |
 | Outside experts | `assignment_list` |
 | Operator jobs | `jobs_list`, `job_show`, `job_changes`, `job_start`, `job_steer`, `job_cancel`, `job_pause` |
 | Continue and procedures | `job_continue`, `procedure_save`, `procedure_show`, `procedure_run` |
@@ -1040,7 +1123,9 @@ Some tools behave differently from their commands:
   `steps`, `retry_budget`, and `spend_budget_cents` directly. As with every
   tool, a top-level argument the tool does not declare is dropped.
   `gate_set` takes `issue`, `gate` (a key, label, or condition id), and
-  `satisfied`.
+  `satisfied`. The plan tools' `id` is the plan's id or its root issue's
+  identifier, as for the commands; `plan_list` takes `team`, `status` and
+  `limit`, and `issue_show` carries the issue's `plan`.
 - An API error's details come back in the tool error text: a validation
   error's fields, and an invalid plan's violations, one per line by step
   key.
@@ -1100,16 +1185,32 @@ directory the way git finds `.git`, gives every clone of a repo the same
 defaults:
 
 ```json
-{ "team": "CLI" }
+{ "team": "CLI", "org": "3f96a9c0-1584-4c65-9c4b-056055024bc9" }
 ```
 
 | Field | Effect |
 | --- | --- |
 | `team` | Default team key. Precedence: `--team`, then `HARNESS_TEAM`, then the repo config. |
 | `url` | Target host. `HARNESS_API_URL` takes precedence. Before an automatic login opens a browser at a host that only the repo names, the CLI asks for confirmation, once per host. |
-| `org` | Reserved. It is parsed but has no effect yet. |
-
-A malformed file is ignored with a warning on stderr.
+| `org` | Organization UUID selecting an org-bound login. Login verifies the server-reported org before storing it. The org never derives a hostname or becomes an API header. |
+
+A malformed file is ignored with a warning on stderr. An invalid org UUID
+refuses the command. With `org`, the host defaults to `https://harness.infra.one`
+unless `url` or `HARNESS_API_URL` specifies it. The repo-selected host passes
+the same once-per-host trust prompt as a repo `url` before browser login.
+
+Sign in once with `harness login` from the repo and select its organization
+on the page. Org logins use separate host-and-org-keyed credential files,
+so logging into one org does not overwrite or revoke another org's login.
+The legacy `credentials.json` remains unchanged and is used by repos without
+`org`. When adding `org` to an existing repo, log in again for that org; the
+legacy credential is not assumed to belong to it. `logout` revokes and
+forgets only the selected login. Explicit `HARNESS_API_TOKEN` credentials
+override org selection; their authority remains whatever the server minted.
+An org-specific login accepts only a credential whose session describes that
+organization. Outside-expert `pxc_` credentials have no org description, so
+use them from a repo without `org` or pass them explicitly through
+`HARNESS_API_TOKEN`.
 
 ### Hosts and tokens
 
@@ -1123,13 +1224,14 @@ refuses with exit code 2 instead of sending the token there. Set
 `HARNESS_API_URL` explicitly if you do mean that host. Without
 `HARNESS_API_TOKEN`, a repo-named host needs a login of its own, and the
 automatic login asks for confirmation first, as described above. Plain
-`http://` is accepted only for localhost.
+`http://` is accepted only for `localhost`, any `*.localhost` host (such as
+a local `harness.infraone.localhost` dev server), `127.0.0.1` and `[::1]`.
 
 ### Environment variables
 
 | Variable | Effect |
 | --- | --- |
-| `HARNESS_API_URL` | Target host (https, or http against localhost only). |
+| `HARNESS_API_URL` | Target host (https, or http against `localhost`, `*.localhost`, `127.0.0.1` or `[::1]` only). |
 | `HARNESS_API_TOKEN` | An `aone_…` API token, or an outside expert's `pxc_…` credential. It takes precedence over the stored login. Headless use only. |
 | `HARNESS_ACTOR` | Write attribution, sent only when set. Without it the server attributes writes to the signed-in user, or for `aone_` tokens to the token's name. Headless use only. |
 | `HARNESS_TEAM` | Default team key for commands that take `--team`. |
@@ -1143,6 +1245,7 @@ automatic login asks for confirmation first, as described above. Plain
 
 | Path | Contents |
 | --- | --- |
+| `~/.config/harness/credentials-org-<hash>.json` | A server-verified org login, keyed by host and org UUID, mode 0600; same `{url, token}` format. |
 | `~/.config/harness/credentials.json` | The stored login: one `{url, token}` pair, mode 0600. |
 | `~/.config/harness/trusted-hosts.json` | Repo-config hosts you agreed to log in to. |
 | `~/.cache/harness/attachments/` | Images downloaded by `show` (or `HARNESS_CACHE_DIR`). |