@allocator-one/harness-cli 1.12.1 → 1.13.0

package/README.md

@@ -1,206 +1,370 @@
 # @allocator-one/harness-cli
 
-CLI and MCP server for [Harness](https://harness.infra.one), allocator.one's
-issue tracker. A standalone Node client — no backend checkout, no Erlang
-toolchain, and no local issue state: issues live server-side, so there is
-nothing to commit or sync.
+The `harness` CLI and MCP server for [Harness](https://harness.infra.one),
+allocator.one's issue tracker. It is a standalone Node client that keeps no
+local issue state. Issues live on the server, so there is nothing to commit or
+sync.
 
 ## Install
 
-Zero-install, always current:
-
-```sh
-npx -y @allocator-one/harness-cli list --team ALL
-```
-
-Or globally:
-
 ```sh
 npm i -g @allocator-one/harness-cli
 harness ready
 ```
 
-Requires Node >= 20.
-
-## Auth
-
-No setup needed: commands target `https://harness.infra.one` and start the
-browser login the first time. One login covers every shell, worktree, and
-agent slot on a machine — credentials are stored at
-`~/.config/harness/credentials.json` (0600) as a single `{url, token}` pair,
-and a token is only ever sent to the host that minted it.
-
-- `harness login` — browser flow (PKCE loopback); `--no-browser` prints the
-  URL and prompts for a pasted token instead.
-- `harness logout` — revokes the stored login server-side and deletes the file.
-- `harness whoami` — shows the resolved host and credential source.
-
-Headless contexts (agents, CI): mint an `aone_…` API token (admin → API
-tokens) and set `HARNESS_API_TOKEN`. Do not set it in interactive sessions —
-the browser login attributes writes to the real user.
-
-### Provider keys
-
-Admins store the org's provider API keys (Anthropic, OpenAI, Google,
-OpenRouter, Brave Search, Perplexity) in Harness under `Settings → Model
-keys`. The CLI hands them to tooling without ever printing them:
-
-- `harness keys list` — provider slugs the org has keys for and the env var
-  each maps to (`--json` for `{providers: [{provider, env}]}`); values are
-  never shown.
-- `harness keys exec [--only <slugs>] [--override] -- <command> [args…]` —
-  runs the command with the keys in its environment and exits with the
-  command's exit code (128 + signal number when it was signalled). `--only
-  brave,perplexity` passes just those providers and withholds your shell's
-  own copies of the other provider variables, so the tool sees no more than
-  it needs; a requested provider the org has no key for keeps your shell's
-  variable (and says so on stderr). Slugs are trimmed and case-insensitive,
-  and an allowlist that names nothing (`--only ,`) is a usage error, not
-  "everything". Otherwise a variable already set in your shell wins unless
-  `--override` is given; a blank variable counts as unset. `--json` is
-  accepted for uniformity but changes nothing: stdout belongs to the command. A SIGTERM sent to
-  `harness` is forwarded to the command; Ctrl+C reaches the command from the
-  terminal directly and `harness` waits to report its exit. macOS and Linux
-  only.
-
-Slug → variable, the same table rcl uses: anthropic → `ANTHROPIC_API_KEY`,
-openai → `OPENAI_API_KEY`, google → `GEMINI_API_KEY`, openrouter →
-`OPENROUTER_API_KEY`, brave → `BRAVE_API_KEY`, perplexity →
-`PERPLEXITY_API_KEY`. Reading keys needs the `model-keys:read` scope: login
-tokens carry it, `aone_` tokens must be minted with it. There is deliberately
-no MCP tool for this — a tool result is model-visible text.
-
-## Environment variables
-
-| Variable | Effect |
-| --- | --- |
-| `HARNESS_API_URL` | Target host (default `https://harness.infra.one`). https only, plain http allowed against localhost. |
-| `HARNESS_API_TOKEN` | Bearer token (`aone_…`); wins over the stored login. Never inherits the stored login's host. |
-| `HARNESS_TEAM` | Default team key for commands that take `--team`. |
-| `HARNESS_ACTOR` | Write attribution, sent only when explicitly set. |
-| `HARNESS_CACHE_DIR` | Where `show` downloads attached images (default `$XDG_CACHE_HOME/harness/attachments` or `~/.cache/harness/attachments`). Absolute paths only. |
-
-## For agents
-
-`harness mcp` runs a stdio MCP server exposing every operation as a typed
-tool — issue_list, issue_show, activity_list, issue_create, issue_update, issue_claim,
-issue_close, issue_comment, issue_comment_edit, issue_comment_delete,
-relation_list/create/update/delete, relation_add/rm (blocking shorthand),
-link_list/add/update/rm,
-project_list/show/create/update, milestone_list/create,
-document_list/show/create/update, label_list/create, team_list,
-team_create, workflow_states, user_list, stats, upload. Read-only tools carry
-`readOnlyHint`. Results are compact JSON of the data envelope.
-
-Register it with Claude Code:
+Or run it without installing:
 
 ```sh
-claude mcp add --scope user harness -- npx -y @allocator-one/harness-cli mcp
+npx -y @allocator-one/harness-cli ready
 ```
 
-Example tool call: `issue_list` with `{"ready": true, "team": "ALL"}`
-returns the ready queue as JSON; `issue_claim` with `{"id": "IO-123"}`
-claims atomically (a conflict means someone else holds it).
-
-Read the same mixed timeline shown in an issue's Activity section with
-`harness activity IO-123`. It returns the newest 20 entries and points out
-when older entries exist; pass `--all` to follow the opaque cursors through
-the full history. `activity_list` exposes the same `id`, `limit`, and `all`
-inputs to MCP clients. Assignment, reassignment, and unassignment entries show
-the actor and previous/new assignees when supplied by the server. Unavailable
-identities use safe labels rather than raw user ids.
+Requires Node >= 20.
 
-Typed issue relations are available without losing the concise blocking
-workflow. `harness dep add|rm` and the `relation_add`/`relation_rm` MCP tools
-remain the blocker-first shorthand; the full surface is:
+## Sign in
+
+You don't need to configure anything. Commands target
+`https://harness.infra.one`, and the first command you run in a terminal
+opens a browser login and then carries on. One login covers every shell,
+worktree, and agent slot on the machine.
+
+- `harness login`: browser sign-in (PKCE, loopback callback on 127.0.0.1).
+  `--no-browser` prints the URL and asks you to paste the token instead.
+  `--url <host>` signs in to another host, and `--timeout <ms>` changes how
+  long it waits for the callback (default 3 minutes). Login tokens last
+  about 30 days.
+- `harness logout`: revokes the stored login on the server and deletes it
+  locally.
+- `harness whoami`: shows the resolved host and where the credential came
+  from.
+
+The automatic login only runs when stdout is a terminal and `CI` is unset
+or empty. Elsewhere (agents, CI, pipes), a command that has no credential
+prints how to authenticate and exits with code `2`. For those headless
+contexts, mint an `aone_…` API token (admin → API tokens) with the
+`harness:read` scope, adding `harness:write` if the workflow changes
+anything (claim, create, update, comment, close), and export it as
+`HARNESS_API_TOKEN`.
+
+> **Never set `HARNESS_API_TOKEN` or `HARNESS_ACTOR` in an interactive
+> session.** The browser login attributes writes to the real user, and
+> overriding it falsifies the audit trail. Both variables are only for
+> headless CI and agent slots.
+
+Every identifier includes its team key, as in `CLI-12` or `ALL-4901`. Older
+issues keep legacy prefixes: `IO-` issues were created before team-prefixed
+numbering, `ALL-` numbers up to the import ceiling came from Linear, and
+`BD-` from beads.
+
+## Daily workflow
 
 ```sh
-harness relation list IO-123
-harness relation add IO-123 IO-456 --type related
-harness relation update IO-123 IO-456 --type blocks
-harness relation rm IO-123 IO-456
+harness ready --claim --all                     # pick and claim the top uncontested issue
+harness show CLI-12                             # read it, including attached screenshots
+# … do the work …
+harness close CLI-12 --reason "Implemented in 1a2b3c4"
 ```
 
-Relation update and removal accept either the relation id from `relation list`
-or a unique related issue identifier. If the same pair has more than one
-relation, the CLI refuses to guess and requires the relation id. Link updates
-use the same safe lookup rule by id or exact URL; the existing `link rm`
-command keeps its first-match behavior for backward compatibility:
+**Queue.** `harness ready` lists open, unblocked issues, highest priority
+first. Blocked issues, `hold`-labeled issues, and parents with open children
+are excluded. `--claim` claims the first issue in that ranking that nobody
+else holds. It tries up to 10 issues and exits `1` with "No claimable
+ready issues" when none can be claimed. Pass `--all` so that the ranking
+covers the whole ready set rather than just the first page. `harness
+blocked` lists issues that are waiting on a blocker. Both commands take
+`--team`.
+
+**Read.** `harness show <id>` prints the fields, relations, children, and
+comments. It also downloads the images attached to the issue's description,
+design, acceptance criteria, notes, and comments (up to 20, cached locally)
+and prints their paths. Screenshots are often the reproduction, so read
+them. `--no-images` skips the downloads. If a download fails, a stderr
+notice says so and the command still succeeds. `harness comments <id>`
+prints the full, untruncated comment thread with comment ids.
+`harness activity <id>` prints the issue's activity timeline: comments,
+creation, and state and assignee changes. It shows the newest 20 entries
+(`--limit` accepts 1–100), and `--all` reads further back.
+
+**Create.** Creating an issue before you write code keeps the work tracked:
 
 ```sh
-harness link update IO-123 https://example.com/old --url https://example.com/new --title "Runbook"
+harness create --title "Fix login redirect" --type bug --priority high \
+  --description "…" --parent CLI-3 --assignee me --due-date 2026-11-01 \
+  --label regression --idempotency-key fix-login-redirect-1
 ```
 
-Issue creation resolves `--label` names within the target team first, then at
-workspace scope. Missing names are created at workspace scope before the issue
-is filed, and the final label ids travel in the single issue-create request, so
-a preparation or permission failure cannot leave an unlabeled issue behind.
-Creating a missing label requires Harness administrator standing.
-
-Label repair is additive and repeatable; it never implicitly replaces the
-whole set:
+- `--type task|bug|feature|epic` is applied as a `type/<type>` label.
+- `--priority urgent|high|medium|low|none` takes names only. Bare numbers
+  are refused because bd and Harness number priorities differently.
+- `--team <key>` falls back to `HARNESS_TEAM` and then to the repo config.
+  With none of these set, the command is a usage error.
+- `--label` (repeatable) looks for a matching label in the target team first
+  and then at workspace scope. Missing labels are created at workspace scope
+  (which requires Harness administrator standing) before the issue is filed,
+  and the issue is created in a single request with all its labels.
+- `--idempotency-key <key>` (1–200 printable ASCII characters, no leading or
+  trailing space) makes a retry safe. If a create times out, run it again
+  with the same key to get the original issue back instead of a duplicate.
+  The CLI never retries a write on its own.
+- `--design`, `--notes`, and `--acceptance` set the remaining text fields.
+
+**Update.** `harness update <id>` with:
+
+- `--claim`: atomic. It assigns you and moves the issue to the team's first
+  started state. A conflict means someone else holds the issue. 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`,
+  `--parent`, `--assignee` (`""` unassigns), `--due-date` (`""` clears).
+- `--notes` replaces the notes and `--append-notes` appends to them. Pass
+  only one of the two.
+- `--add-label` / `--remove-label` (repeatable, name or id) add or remove
+  individual labels without replacing the rest. You can only add labels that
+  belong to the issue's team or the workspace, and a missing name is created
+  at workspace scope, as with `create`. If two attached labels match a name,
+  remove by id.
+
+**Dependencies.** `harness dep add <issue> <blocker>`: **the second argument
+blocks the first.** `harness dep rm <issue> <blocker>` removes the
+dependency. For other relation types, see `relation` under
+[Other commands](#other-commands).
+
+**Close.** `harness close <id> [<id>…]` closes one or more issues as
+completed. Use `--cancel` to close them as canceled, or `--duplicate-of <id>`
+to close a single issue as a duplicate of the canonical one. The
+duplicate-of form records a duplicate relation and cannot be combined with
+`--cancel`. `--reason` records why the issue is done. The output lists the
+issues each closure unblocked
+(`Closed CLI-12 — unblocked: CLI-13, CLI-14`); act on them instead of
+leaving them in the queue. With several ids, each one is closed on its own.
+A failure prints `FAILED <id>: …`, and the command exits `1` after trying
+the rest. `harness archive <id>…` archives issues, `--restore` brings them
+back, and `harness list --scope archived` lists them.
+
+**Comment.** `harness comment <id> "text" [--mention <name>]…` posts a
+comment. The server resolves each mention and notifies that person.
+`harness comment edit <id> <comment-id> "new text"` and
+`harness comment delete <id> <comment-id>` (alias `rm`) work on your own
+comments. Comment ids are UUIDs from `harness comments`.
+
+**Find.** There are two search commands:
+
+- `harness search <question…>` searches by meaning. It returns a ranked list
+  with an exact identifier first, followed by results ordered by relevance
+  across a lexical and a semantic signal, so it can find issues that share
+  none of your words. Write the question in plain language instead of
+  keywords. Results default to 10 and are capped at 20, with no pages
+  (`--page`/`--all` are accepted but ignored). Archived issues are not
+  searched. If the semantic side is unavailable, stderr says
+  `semantic search unavailable — showing lexical matches only`.
+- `harness list --search <text>` is the paginated lexical filter, which
+  matches title or issue number.
+
+`harness list` filters: `--status open|in_progress|closed`,
+`--assignee <me|id|email|name|"">` (`""` means unassigned),
+`--created-by <me|id>`, `--involved me`, `--priority <name>`,
+`--label <name>` or `--type <type>` (only one of the two), `--team <key>`,
+`--parent <id>` (children of an epic), and `--scope all|archived`.
+
+**Overview.** `harness stats` prints per-team and total counts.
+`harness prime` prints those counts, the top of the ready queue, and a
+short workflow reminder. It is meant for the start of an agent session.
+
+### Text from a file
+
+When text comes from somewhere other than your own typing, such as issue
+content, a commit message, or model output, pass a file instead of a shell
+argument. Quoting can be defeated: a `"` ends the string, `$(…)`
+substitutes, and a heredoc ends at any flush-left delimiter line the text
+happens to contain.
 
 ```sh
-harness update IO-123 --add-label security --add-label needs-review
-harness update IO-123 --remove-label security
+harness create --title "…" --description-file ./body.md
+harness update CLI-12 --notes-file ./notes.md --acceptance-file ./ac.md
+harness comment CLI-12 --body-file ./comment.md
+git log -1 --format=%B | harness close CLI-12 --reason-file -
 ```
 
-Both update flags accept a label name or id. Additions allow only labels from
-the issue's team or workspace. Removal can target an attached legacy foreign
-label; when attached normalized names are ambiguous, use the label id.
-
-Auth resolution is identical to the CLI. Without a credential, tools return
-an error telling the agent to run `harness login` in a terminal — the
-server never opens a browser itself.
+| Command | File options |
+| --- | --- |
+| `create` | `--title-file`, `--description-file`, `--design-file`, `--notes-file`, `--acceptance-file` |
+| `update` | the same five, plus `--append-notes-file` |
+| `close` | `--reason-file` |
+| `comment`, `comment edit` | `--body-file` |
+
+Other commands (`project`, `milestone`, `doc`, `link`, and so on) take inline
+values only. `-` reads from stdin, and only one option per invocation can do
+that. stdin must not be a terminal. Passing both the inline and the file form
+of a field is a usage error, and so is a file that produces an empty title,
+reason, or comment. Conflicting options are caught before anything is read,
+so a rejected command never consumes your pipe. A file must be valid UTF-8
+and at most 1 MB, and one trailing newline is dropped, as with
+`$(cat file)`.
+
+## Uploads
+
+`harness upload <path>` uploads a file and prints a markdown reference to
+paste into a description or comment. `--json` returns the URL, filename,
+content type, byte size, and markdown instead.
+
+- Images (PNG, JPG, WebP, GIF) can be up to 25 MB.
+- Videos must be `.mp4` files of up to 100 MB, with H.264 8-bit 4:2:0 video,
+  optional AAC audio, and optional mov_text subtitles. The server validates
+  the media and does not transcode other formats. Harness shows linked
+  videos as an inline player.
+
+A new video is private to its uploader until that user saves its link in an
+issue description or comment. After that it follows the access policy of
+the issue that holds it, and reusing the link elsewhere doesn't change who
+owns it. `harness show` downloads images only, never videos. The older
+`attach-image <path>` command accepts images only (25 MB).
+
+## Other commands
+
+| Command | Notes |
+| --- | --- |
+| `relation list <issue>` | Every typed relation, with relation ids. |
+| `relation add <issue> <other> --type <t>` | `blocks`, `blocked_by`, `related`, `duplicate`, `duplicate_of`, `duplicated_by`. |
+| `relation update <issue> <relation-id-or-issue> --type <t>` | `blocks`, `blocked_by`, `related`, `duplicate_of`. |
+| `relation rm <issue> <relation-id-or-issue>` | If more than one relation matches the other issue, pass the relation id. |
+| `link list\|add\|update\|rm <issue> …` | URLs attached to an issue. `add <issue> <url> [--title]`; `update <issue> <link-id-or-url> --url … \| --title …` refuses an ambiguous URL; `rm <issue> <link-id-or-url>` removes the first match. |
+| `project list\|show\|create\|update` | `list [--search] [--state]` (paginated). `create --name … [--description] [--summary] [--state] [--lead <user-id>] [--start-date] [--target-date]`. |
+| `milestone list\|create --project <id>` | `create … --name … [--description] [--target-date]`. |
+| `doc list\|show\|create\|update` | `list [--search]` (paginated). `create --title … [--content] [--project <id>]`. |
+| `label list\|create\|update\|delete` | `create <name> [--color]`, `update <id> [--name] [--color]`, `delete <id> --yes` (refused while issues carry the label). |
+| `team list\|create\|rename\|set-default` | `create --key <KEY> --name …` sets up the default workflow states. The key is permanent; `rename <key> --name …` changes only the display name. `set-default <key>` makes the team the org's default filing target. |
+| `state list\|add\|update\|order\|delete` | A team's workflow states (`--team`, else `HARNESS_TEAM` or the repo config). `add --name … --type backlog\|unstarted\|started\|completed\|canceled [--color]`, `order <id,id,…>` (every state id, in order), `delete <id> --yes`. `states` is an alias of `state list`. |
+| `member list\|add\|set-role` | The org's tracker roster. `add --email … --role admin\|staff\|collaborator`, `set-role <user-id> --role …\|none` (`none` revokes). |
+| `user list` | Users, for resolving assignees. |
+| `version` | CLI and server API versions. Works before you log in, and so does `harness --version`. |
+
+`team rename`, `team set-default`, `label update`, `label delete`, and the
+write commands of `state` and `member` require Harness administrator
+standing, and so does `member list`.
+
+## Provider keys
 
-### Text from a file, never from a shell argument
+Admins store the org's provider API keys (Anthropic, OpenAI, Google,
+OpenRouter, Brave Search, Perplexity) in Harness under `Settings → Model
+keys`. `harness keys` passes them to tools without ever printing them:
 
-Every free-text option has a `--<field>-file` companion, and `-` means stdin:
+- `harness keys list` shows the provider slugs the org has keys for and the
+  environment variable each one maps to (`--json` returns
+  `{providers: [{provider, env}]}`). It never prints the values.
+- `harness keys exec [--only <slugs>] [--override] -- <command> [args…]`
+  runs the command with the keys in its environment and exits with the
+  command's exit code (128 + the signal number if the command was killed by a
+  signal). `--only brave,perplexity` passes just those providers and also
+  removes your shell's own copies of the other provider variables, so the
+  command sees only what it needs. If the org has no key for a provider you
+  requested, your shell's variable is kept and stderr says so. Slugs are
+  trimmed and case-insensitive. An `--only` list that names nothing
+  (`--only ,`) is a usage error, not a request for everything. Without
+  `--override`, a variable that is already set in your shell wins (a blank
+  variable counts as unset). `--json` is accepted but has no effect, because
+  stdout belongs to the command. A SIGTERM sent to `harness` is forwarded to
+  the command. Ctrl+C reaches the command directly from the terminal, and
+  `harness` waits to report its exit. Works on macOS and Linux only.
+
+Each slug maps to the same variable as in rcl: anthropic → `ANTHROPIC_API_KEY`,
+openai → `OPENAI_API_KEY`, google → `GEMINI_API_KEY`, openrouter →
+`OPENROUTER_API_KEY`, brave → `BRAVE_API_KEY`, perplexity →
+`PERPLEXITY_API_KEY`. Reading keys requires the `model-keys:read` scope.
+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.
+
+## Scripting contract
+
+- **`--json` on every command** except `mcp`. It replaces the human output
+  with the response data as JSON. `keys exec` accepts it but changes
+  nothing: its stdout is the child command's output.
+- **stdout carries data only**, so it is safe to pipe. Diagnostics go to
+  stderr:
+  - `→ https://harness.infra.one` on every command that writes, naming the
+    host it sent the write to.
+  - `harness: showing 50 of 132 (page 1 of 3) — pass --all for the rest, or --page to step through.`
+    when a paginated read did not return everything, and
+    `harness: --limit N was capped at M by the server.` when the server
+    reduced the page size you asked for.
+  - The `activity`, `search`, and `show` notices described above.
+  - The update notice (see [Staying current](#staying-current)).
+- **Pagination.** `ready`, `blocked`, `list`, `project list`, and `doc list`
+  return 50 records per page by default. `--limit` changes the page size,
+  `--page` selects a page, and `--all` follows every page (pass `--all` or
+  `--page`, not both). The truncation notice goes to stderr only, so a
+  script that reads just the `--json` output cannot tell a full page from a
+  complete result. Pass `--all` when you need everything.
+- **Exit codes.** `keys exec` returns the command's exit code instead.
+
+  | Code | Meaning |
+  | --- | --- |
+  | `0` | Success. |
+  | `1` | The command failed. Causes include an API error (the message gives the HTTP status), a failure such as nothing being claimable, a partial failure across several ids, or a local refusal such as an unreadable or oversized upload. |
+  | `2` | Usage or configuration error, including "not signed in" outside a terminal. Nothing was sent. |
+  | `3` | The API was unreachable (DNS, TLS, connection refused, or timeout). Retry with backoff, and if the API stays down, say so instead of dropping tracked work. |
+
+## MCP server
+
+`harness mcp` runs an MCP server over stdio. To register it with Claude Code:
 
 ```sh
-harness create --title "…" --description-file ./body.md
-harness update IO-123 --notes-file ./notes.md --acceptance-file ./ac.md
-harness comment IO-123 --body-file ./comment.md
-git log -1 --format=%B | harness close IO-123 --reason-file -
+claude mcp add --scope user harness -- npx -y @allocator-one/harness-cli mcp
 ```
 
-`create` and `update` cover `--title`, `--description`, `--design`, `--notes`
-and `--acceptance` (plus `--append-notes` on `update`); `close` takes
-`--reason-file`, `comment` takes `--body-file`.
-
-Use these whenever the text is not something you authored inline. Prose that
-reaches a shell argument has to survive quoting, and quoting can be defeated —
-a `"` closes the string, `$(…)` substitutes, and a heredoc ends at whatever
-flush-left delimiter line the text happens to contain. Handing over a path
-removes the question, the way `git commit -F` does. This matters most for
-agents relaying issue text they did not write.
-
-Passing both an inline value and its `-file` for the same field is a usage
-error rather than a silent precedence, and only one field per invocation may
-read stdin. Both are checked before anything is read, so a rejected command
-never consumes your pipe. One trailing newline is dropped, like `$(cat file)`.
+With a global install, `harness mcp` works as the command instead of the
+`npx` form. Any other MCP client can use the same command:
 
-## Image and video uploads
-
-`harness upload ./demo.mp4` prints a reusable markdown reference. Paste it
-into an issue description or comment to show an inline video player. Use
-`--json` for the server's URL, filename, content type, byte size, and markdown.
-The MCP `upload` tool accepts the same local path and returns the same metadata.
-
-Images (PNG, JPG, WebP, GIF) can be up to 25 MB. Videos must be `.mp4`, up to
-100 MB, with H.264 8-bit 4:2:0 video, optional AAC audio, and optional mov_text
-subtitles. The server validates the media; it does not transcode other formats.
-
-A newly uploaded video is private to its uploader until that user saves its
-link in an issue description or comment. It then follows the owning issue's
-access policy. Reusing the link elsewhere does not change that ownership.
-`harness show` continues downloading images only, never linked videos.
-The older `attach-image` command retains its 25 MB limit.
+```json
+{ "mcpServers": { "harness": { "command": "npx", "args": ["-y", "@allocator-one/harness-cli", "mcp"] } } }
+```
 
-## Repo config
+The server exposes 52 tools:
 
-A committed `.harness-cli/config.json`, discovered git-style by walking up
-from the working directory, gives every clone of a repo its defaults:
+| Area | Tools |
+| --- | --- |
+| Issues | `issue_list`, `issue_search`, `issue_show`, `activity_list`, `issue_create`, `issue_update`, `issue_claim`, `issue_close`, `issue_archive` |
+| Comments | `issue_comment`, `issue_comment_edit`, `issue_comment_delete`, `comment_list` |
+| Relations | `relation_add`, `relation_rm` (blocking shorthand: `blocker` blocks `issue`), `relation_list`, `relation_create`, `relation_update`, `relation_delete` |
+| Links | `link_list`, `link_add`, `link_update`, `link_rm` |
+| Projects and docs | `project_list`, `project_show`, `project_create`, `project_update`, `milestone_list`, `milestone_create`, `document_list`, `document_show`, `document_create`, `document_update` |
+| 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` |
+| Other | `stats`, `upload` |
+
+The tools cover the issue workflow and the admin surface. Some commands are
+CLI-only: `keys` (deliberately), `login`/`logout`/`whoami`, `version`, and
+`prime`. Read-only tools carry `readOnlyHint`. Each result is compact JSON
+of the response data. Any stderr notice the CLI would print, such as
+truncation, is added as a second text item. A partial failure across several
+ids is returned as an error, with the details for each id in the JSON.
+Some tools behave differently from their commands:
+
+- `issue_list` with `ready: true` or `blocked: true` accepts every list
+  filter. The CLI's `ready` and `blocked` take only `--team`.
+- `issue_show` downloads images only when you pass `images: true`.
+- `state_delete` and `label_delete` don't need the CLI's `--yes`.
+
+For example, `issue_list` with `{"ready": true, "team": "CLI"}` returns the
+ready queue, and `issue_claim` with `{"id": "CLI-12"}` claims an issue
+atomically. `issue_close` takes `ids`, `reason`, `cancel`, and
+`duplicate_of`, and `issue_create` takes an `idempotency_key` for safe
+retries.
+
+The MCP server resolves auth exactly as the CLI does, on every call, so a
+login completed while the server is running takes effect without a restart.
+It never opens a browser. Without a credential, a tool returns an error that
+tells the agent to run `harness login` in a terminal or set
+`HARNESS_API_TOKEN`.
+
+## Configuration
+
+### Repo config
+
+A committed `.harness-cli/config.json`, found by walking up from the working
+directory the way git finds `.git`, gives every clone of a repo the same
+defaults:
 
 ```json
 { "team": "CLI" }
@@ -208,47 +372,90 @@ from the working directory, gives every clone of a repo its defaults:
 
 | Field | Effect |
 | --- | --- |
-| `team` | Default team key. Precedence: `--team` > `HARNESS_TEAM` > repo config. |
-| `url` | Target host. `HARNESS_API_URL` wins. Tokens stay host-bound: a stored login only serves the host that minted it, an env `HARNESS_API_TOKEN` refuses to pair with a repo-named host (set `HARNESS_API_URL` explicitly), and before the interactive auto-login opens a browser at a host named only by the repo, the CLI asks once per host (remembered in `~/.config/harness/trusted-hosts.json`). |
-| `org` | Reserved for Harness org-scoping; parsed today, `url` wins meanwhile. |
-
-This is config, not state — issues stay server-side.
-
-## Development
+| `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. |
 
-```sh
-npm ci
-npm run typecheck
-npm test
-npm run build          # bundles to dist/cli.js (tsup)
-node dist/cli.js version
-```
+A malformed file is ignored with a warning on stderr.
 
-The OpenAPI spec is vendored at `spec/openapi.json` and TypeScript types are
-generated into `src/generated/` (committed, so npx consumers never run
-codegen):
+### Hosts and tokens
 
-```sh
-npm run spec:refresh   # fetch the spec from a live host (uses your login)
-npm run codegen        # regenerate src/generated/api.ts from the vendored spec
-```
+The host comes from `HARNESS_API_URL`, then the repo config's `url`, then
+the host of the stored login, then `https://harness.infra.one`. Tokens are
+bound to the host that issued them. A stored login is only sent to the host
+that issued it. `HARNESS_API_TOKEN` is only sent to `HARNESS_API_URL`, or to
+the default host when that variable is unset. It is never sent to the stored
+login's host, and when a repo config names another host, the command
+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.
 
-CI regenerates the types and fails on drift.
+### Environment variables
 
-## Release
+| Variable | Effect |
+| --- | --- |
+| `HARNESS_API_URL` | Target host (https, or http against localhost only). |
+| `HARNESS_API_TOKEN` | An `aone_…` API token. 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`. |
+| `HARNESS_CACHE_DIR` | Where `show` stores downloaded images. Must be an absolute path. |
+| `HARNESS_NO_UPDATE_CHECK` | Set to a value other than `0`, `false`, or `no` to turn off the update notice and the automatic upgrade. |
+| `HARNESS_AUTO_UPGRADE=0` | Keeps the notice but never installs anything (`false` and `no` also work). |
+| `CI` | Any value other than empty, `0`, `false`, or `no` turns off the update notice and automatic upgrade. Separately, any non-empty value, including `0`, stops the automatic browser login. |
+| `XDG_CONFIG_HOME`, `XDG_CACHE_HOME` | Used instead of `~/.config` and `~/.cache` when set to absolute paths. |
 
-First bump `package.json` and `package-lock.json` through a pull request. After
-that PR is squash-merged, fetch `main` and tag the merge commit — never the
-pre-merge branch tip. Pushing the tag starts the Release workflow, which builds,
-tests, and publishes to npm:
+### Files
 
-```sh
-git fetch origin main
-git tag -a vX.Y.Z MERGE_COMMIT_SHA -m "Release vX.Y.Z"
-git push origin vX.Y.Z
-```
-
-Publishing requires the `NPM_TOKEN` actions secret (an automation token for
-the `allocator-one` npm org). Provenance attestation is disabled: npm only
-accepts it from public source repositories, and this repo is private — turn
-`--provenance` back on in `release.yml` if the repo ever goes public.
+| Path | Contents |
+| --- | --- |
+| `~/.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`). |
+| `~/.cache/harness/update-check.json` | The daily update-check stamp. |
+| `~/.cache/harness/upgrade.lock` | Held while an automatic upgrade runs. |
+
+None of these files is tracker state: issues stay on the server. The
+attachment cache does hold copies of issue images, so clear it when you no
+longer need them.
+
+## Staying current
+
+**Notice.** Each run reads the cached stamp and prints at most one stderr
+line when a newer release exists:
+`harness: 1.13.0 is available (you have 1.12.1) — npm i -g @allocator-one/harness-cli@latest`.
+When the stamp is more than a day old, a detached background process
+refreshes it from the npm registry. A command never waits on that network
+request. The notice applies only to global and project-local installs, not
+to `npx` or a git checkout.
+
+**Automatic upgrade on HTTP 426.** The CLI sends its version with every
+request, and the server refuses versions below its minimum with a 426. In
+that case the CLI runs
+`npm install --global --ignore-scripts @allocator-one/harness-cli@latest`,
+re-runs the original command, and exits with that command's exit code.
+Re-running is safe only for this status. The server answers 426 before
+authentication and before the request handler, so the refused request
+changed nothing. The CLI never retries any other failure. The upgrade is
+limited by these guards:
+
+- It only upgrades a global install, located through `npm root -g`, and
+  only when that directory is writable.
+- Only one upgrade runs at a time on a machine (a lock under
+  `~/.cache/harness`). A process that finds a newer version already
+  installed re-runs with it directly.
+- `--ignore-scripts` means an unattended upgrade never runs package scripts.
+- The re-run carries `HARNESS_UPGRADED=1`, so each command is upgraded at
+  most once.
+- It is skipped for `npx`, project-local installs, git checkouts, inside
+  `harness mcp`, under `CI`, and when `HARNESS_NO_UPDATE_CHECK` or
+  `HARNESS_AUTO_UPGRADE=0` is set.
+
+When the upgrade is skipped or fails, the command prints the server's
+message, adds the reason if the upgrade was attempted, and exits `1`.
+
+---
+
+Building, testing, and releasing this package are covered in `AGENTS.md`
+in the (private) source repository.

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

@@ -83,8 +83,13 @@ var Client = class {
   async get(path2, params) {
     return this.json(await this.raw("GET", path2, { params }));
   }
-  async post(path2, body = {}) {
-    return this.json(await this.raw("POST", path2, { json: this.withActor(body) }));
+  async post(path2, body = {}, options = {}) {
+    return this.json(
+      await this.raw("POST", path2, {
+        json: this.withActor(body),
+        idempotencyKey: options.idempotencyKey
+      })
+    );
   }
   async patch(path2, body) {
     return this.json(await this.raw("PATCH", path2, { json: this.withActor(body) }));
@@ -138,6 +143,9 @@ var Client = class {
       authorization: `Bearer ${this.config.token}`,
       "x-harness-cli-version": CLI_VERSION
     };
+    if (options.idempotencyKey !== void 0) {
+      headers["idempotency-key"] = options.idempotencyKey;
+    }
     let body;
     if (options.json !== void 0) {
       headers["content-type"] = "application/json";
@@ -664,6 +672,8 @@ var STATUS_STATE_TYPES = {
   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+$/;
 var UUID_FORMAT = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function isUuid(value) {
@@ -810,6 +820,7 @@ async function create(ctx, opts) {
   }
   validateType(opts.type);
   const team = requiredTeam(ctx, opts.team);
+  validateIdempotencyKey(opts.idempotencyKey);
   const priority = optionalPriority(opts.priority);
   const dueDate = optionalDueDate(opts.dueDate);
   const labels = requestedLabelNames(wantedLabels(opts));
@@ -824,7 +835,9 @@ async function create(ctx, opts) {
   body = putDueDate(body, dueDate);
   body = putAssignee(body, opts.assignee);
   if (labelIds.length > 0) body["label_ids"] = labelIds;
-  const created = await ctx.client.post(`/api/v1/teams/${team}/issues`, body);
+  const created = await ctx.client.post(`/api/v1/teams/${team}/issues`, body, {
+    idempotencyKey: opts.idempotencyKey
+  });
   const issue = created.data;
   return {
     json: issue,
@@ -832,6 +845,16 @@ async function create(ctx, opts) {
 `
   };
 }
+function validateIdempotencyKey(key) {
+  if (key === void 0) return;
+  if (key.trim() === "") throw new UsageError("idempotency key must not be blank");
+  if (Buffer.byteLength(key, "utf8") > MAX_IDEMPOTENCY_KEY_BYTES) {
+    throw new UsageError(`idempotency key must not exceed ${MAX_IDEMPOTENCY_KEY_BYTES} UTF-8 bytes`);
+  }
+  if (!IDEMPOTENCY_KEY_FORMAT.test(key)) {
+    throw new UsageError("idempotency key must use printable ASCII and cannot start or end with a space");
+  }
+}
 async function update(ctx, identifier, opts) {
   requireIdentifiers([identifier]);
   if (opts.notes !== void 0 && opts.appendNotes !== void 0) {
@@ -896,14 +919,28 @@ ${opts.appendNotes}`;
 `;
   return { json: issue, human };
 }
-async function close(ctx, identifiers, opts) {
+function requireCloseArgs(identifiers, opts) {
   if (identifiers.length === 0) {
-    throw new UsageError("usage: harness close <id> [<id>\u2026] [--reason <text>] [--cancel]");
+    throw new UsageError(
+      "usage: harness close <id> [<id>\u2026] [--reason <text>] [--cancel | --duplicate-of <id>]"
+    );
   }
   requireIdentifiers(identifiers);
+  if (opts.duplicateOf === void 0) return;
+  requireIdentifiers([opts.duplicateOf]);
+  if (opts.cancel === true) {
+    throw new UsageError("--duplicate-of and --cancel are mutually exclusive");
+  }
+  if (identifiers.length !== 1) {
+    throw new UsageError("--duplicate-of accepts exactly one source issue");
+  }
+}
+async function close(ctx, identifiers, opts) {
+  requireCloseArgs(identifiers, opts);
   let body = {};
   body = putPresent(body, "reason", opts.reason);
   body = putPresent(body, "cancel", opts.cancel);
+  body = putPresent(body, "duplicate_of", opts.duplicateOf);
   const results = [];
   for (const identifier of identifiers) {
     try {
@@ -917,22 +954,28 @@ async function close(ctx, identifiers, opts) {
       }
     }
   }
-  const human = results.map((result) => closeLine(result)).join("");
+  const human = results.map((result) => closeLine(result, opts.duplicateOf)).join("");
   const json2 = results.map(
-    (result) => result.ok ? { identifier: result.identifier, closed: true, unblocked: result.response["unblocked"] ?? null } : { identifier: result.identifier, closed: false, error: errorText(result.error) }
+    (result) => result.ok ? {
+      identifier: result.identifier,
+      closed: true,
+      ...opts.duplicateOf === void 0 ? {} : { duplicate_of: opts.duplicateOf },
+      unblocked: result.response["unblocked"] ?? null
+    } : { identifier: result.identifier, closed: false, error: errorText(result.error) }
   );
   const partial = results.some((result) => !result.ok);
   return partial ? { json: json2, human, partial: true } : { json: json2, human };
 }
-function closeLine(result) {
+function closeLine(result, duplicateOf) {
   if (!result.ok) return `FAILED ${result.identifier}: ${errorText(result.error)}
 `;
+  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 `Closed ${result.identifier} \u2014 unblocked: ${unblocked.map(String).join(", ")}
+    return `${closure} \u2014 unblocked: ${unblocked.map(String).join(", ")}
 `;
   }
-  return `Closed ${result.identifier}
+  return `${closure}
 `;
 }
 async function archive(ctx, identifiers, opts) {
@@ -2137,6 +2180,8 @@ export {
   Client,
   clean,
   json,
+  MAX_IDEMPOTENCY_KEY_BYTES,
+  IDEMPOTENCY_KEY_FORMAT,
   requireIdentifiers,
   ready,
   blocked,
@@ -2150,6 +2195,7 @@ export {
   version,
   create,
   update,
+  requireCloseArgs,
   close,
   archive,
   comments,

package/dist/cli.js

@@ -59,6 +59,7 @@ import {
   relationList,
   relationRm,
   relationUpdate,
+  requireCloseArgs,
   requireCommentId,
   requireIdentifiers,
   resolveCacheHome,
@@ -82,7 +83,7 @@ import {
   version,
   workflowStates,
   writeCredentials
-} from "./chunk-VOH6BBJD.js";
+} from "./chunk-XFMECLOU.js";
 
 // src/cli.ts
 import { createInterface as createInterface2 } from "readline";
@@ -1676,7 +1677,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 +1727,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 }
       ]);
@@ -2093,7 +2094,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-CYBKYG5E.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-CYBKYG5E.js}

@@ -4,6 +4,8 @@ import {
   CLI_VERSION,
   Client,
   HttpError,
+  IDEMPOTENCY_KEY_FORMAT,
+  MAX_IDEMPOTENCY_KEY_BYTES,
   RELATION_CREATE_TYPES,
   RELATION_UPDATE_TYPES,
   TransportError,
@@ -61,7 +63,7 @@ import {
   upload,
   userList,
   workflowStates
-} from "./chunk-VOH6BBJD.js";
+} from "./chunk-XFMECLOU.js";
 
 // src/mcp/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -190,13 +192,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: z.string().min(1).max(MAX_IDEMPOTENCY_KEY_BYTES).regex(IDEMPOTENCY_KEY_FORMAT, "must use printable ASCII without leading or trailing spaces").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"]
     })
   },
   {
@@ -237,14 +241,19 @@ var TOOLS = [
   },
   {
     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.",
     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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allocator-one/harness-cli",
-  "version": "1.12.1",
+  "version": "1.13.0",
   "description": "CLI and MCP server for Harness, allocator.one's issue tracker",
   "type": "module",
   "license": "MIT",

package/spec/openapi.json

@@ -1020,7 +1020,7 @@
       "post": {
         "callbacks": {},
         "deprecated": false,
-        "description": "Requires the `harness:write` scope.",
+        "description": "Requires the `harness:write` scope. An optional Idempotency-Key makes deliberate retries safe for the authenticated credential. An identical replay returns the current issue with 200 and Idempotency-Replayed: true; reusing the key for a different request returns 409. Keys use 1-200 printable ASCII characters and cannot begin or end with a space.",
         "parameters": [
           {
             "description": "Team key, e.g. ALL",
@@ -1030,6 +1030,18 @@
             "schema": {
               "type": "string"
             }
+          },
+          {
+            "description": "Credential-scoped printable-ASCII key for retrying this issue creation request",
+            "in": "header",
+            "name": "Idempotency-Key",
+            "required": false,
+            "schema": {
+              "maxLength": 200,
+              "minLength": 1,
+              "pattern": "^[!-~](?:[ -~]*[!-~])?(?![\\s\\S])",
+              "type": "string"
+            }
           }
         ],
         "requestBody": {
@@ -1099,7 +1111,23 @@
         },
         "responses": {
           "200": {
-            "description": "Success"
+            "description": "Idempotent replay",
+            "headers": {
+              "Idempotency-Replayed": {
+                "description": "True when the response replays an earlier issue creation",
+                "required": true,
+                "schema": {
+                  "enum": [
+                    "true"
+                  ],
+                  "type": "string"
+                },
+                "style": "simple"
+              }
+            }
+          },
+          "201": {
+            "description": "Issue created"
           },
           "400": {
             "description": "Bad request"
@@ -1113,6 +1141,9 @@
           "404": {
             "description": "Not found"
           },
+          "409": {
+            "description": "Idempotency key reused for a different request"
+          },
           "422": {
             "description": "Validation error"
           }
@@ -2304,7 +2335,7 @@
       "post": {
         "callbacks": {},
         "deprecated": false,
-        "description": "Requires the `harness:write` scope. Moves the issue to the team's first completed-type state (canceled-type with `cancel`), posting `reason` as a comment first. The response's `unblocked` lists identifiers of issues that became ready because this one closed.",
+        "description": "Requires the `harness:write` scope. Moves the issue to the team's first completed-type state (canceled-type with `cancel`). With `duplicate_of`, atomically records a duplicate relation, moves to the team's duplicate-purpose state, and posts `reason`; `cancel` and `duplicate_of` are mutually exclusive. The response's `unblocked` lists identifiers of issues that became ready because this one closed.",
         "parameters": [
           {
             "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
@@ -2326,11 +2357,18 @@
                     "type": "string"
                   },
                   "cancel": {
-                    "description": "Move to a canceled-type state instead of completed",
+                    "description": "Move to a canceled-type state instead of completed; cannot be used with duplicate_of",
+                    "nullable": true,
                     "type": "boolean"
                   },
+                  "duplicate_of": {
+                    "description": "Canonical issue identifier. Atomically records this issue as its duplicate and closes into the team's duplicate-purpose state; cannot be used with cancel.",
+                    "nullable": true,
+                    "type": "string"
+                  },
                   "reason": {
                     "description": "Optional close reason, posted as a comment",
+                    "nullable": true,
                     "type": "string"
                   }
                 },