@task-handoff/thctl 0.0.35

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,4 @@
+TaskHandoff
+Copyright 2026 TaskHandoff
+
+This product includes software developed by the TaskHandoff project.

package/README.md

@@ -0,0 +1,211 @@
+# Control Plane CLI (`thctl`)
+
+`thctl` is the command line client for the TaskHandoff Control Plane. It connects to one or more Control Plane deployments, authorizes through the existing Web login, and exposes the same authoritative projections and commands as the Control Plane UI in a scriptable contract.
+
+The CLI never owns state: reads consume Control Plane projections, writes go through the shared `@task-handoff/control-plane-client` API layer, and `thctl schema` exports the declared leaf contract (arguments, options, input/output JSON Schema) as the single machine-readable source.
+
+## Install
+
+```bash
+npm install -g @task-handoff/thctl
+thctl --help
+```
+
+`@task-handoff/thctl` is published by the TaskHandoff runtime release pipeline, so the CLI version matches the server runtime packages (`@task-handoff/server`, `@task-handoff/control-plane`, `@task-handoff/node-agent`). Prereleases are available through the `alpha` and `beta` dist-tags.
+
+From a repository checkout:
+
+```bash
+pnpm install
+node bin/thctl.js --help          # repository checkout
+pnpm runtime:pack:thctl           # build the publishable package
+```
+
+`pnpm exec thctl` is not wired in the workspace root: pnpm does not link a project's own bin, so checkout usage goes through `node bin/thctl.js` (or the packed tarball).
+
+## Profiles
+
+A profile is one pinned Control Plane identity. Profiles live in `~/.config/task-handoff/cli` (honoring `XDG_CONFIG_HOME`, overridable through `TASK_HANDOFF_CLI_CONFIG_DIR`).
+
+```bash
+thctl profile add https://control.example.com      # first connect pins the identity fingerprint (TOFU)
+thctl profile add http://127.0.0.1:8787 --label local
+thctl profile list
+thctl profile use local
+thctl profile show
+thctl profile trust <label> --yes                  # re-pin after a verified identity change
+thctl profile remove <label>
+```
+
+- `profiles.json` stores origin, Control Plane ID, signing-key fingerprint, protocol version and the capability snapshot; it never stores secrets.
+- Identity changes are rejected until `profile trust` re-pins the new fingerprint; a normal certificate renewal does not change the fingerprint.
+- The Control Plane must declare the `cliSessions` capability. Servers without it are rejected before login with exit code 14.
+
+## Authorization
+
+`thctl login` reuses the Control Plane Web login as an authorization page; the CLI itself never receives the Web session. The approval page is shown to an already signed-in operator, who approves or denies the request, and the CLI exchanges the approval for its own separately revocable `cli` session.
+
+```bash
+thctl login                  # browser flow: opens /cli/authorize and receives the loopback callback
+thctl login --device         # devices without a browser: user code + verification URL, polled with backoff
+thctl whoami
+thctl logout                 # revokes the CLI session server-side and clears the local credential
+```
+
+- The loopback callback binds `127.0.0.1` on a random port and validates the `state` parameter.
+- The device flow prints the user code and `verificationUriComplete`, then polls the token endpoint; `slow_down` doubles the interval, denial and expiry surface as exit code 5.
+- The session token is stored in `credentials.json` (0600, directory 0700), never in `profiles.json`.
+- CLI sessions appear in the Control Plane session settings and can be revoked there; a revoked session clears the local credential on the next 401.
+- Sessions renew automatically when less than seven days remain.
+
+## Local desktop Control Plane
+
+When the desktop app runs its Control Plane without user management (`--auth-mode disabled`), `thctl` connects without any profile setup or Web login:
+
+```bash
+thctl whoami        # discovers the local Control Plane, writes the managed `local` profile, mints a local CLI session
+```
+
+- Discovery reads the user-level runtime lock (`${TMPDIR}/task-handoff-control-plane-<uid>.lock`, overridable through `TASK_HANDOFF_CONTROL_PLANE_LOCK_PATH`), checks that the recorded owner process is alive with a matching start identity, takes the loopback host and port, and verifies the signed identity document. Port scanning, LAN addresses and non-loopback origins are never trusted.
+- The first discovery writes a managed profile: label `local` (or an origin-derived label if `local` is taken), `source: local-discovery`, pinned to the presented identity (TOFU), and set as the default only when no default exists. Manual profiles are never overwritten, and a manual profile for the same origin is reused instead.
+- These servers declare `localCliSessions: true` instead of `cliSessions`. That capability allows session minting only on loopback: with no stored credential the CLI calls `POST /api/auth/cli/local` and stores the returned session in `credentials.json` (0600).
+- A disabled Control Plane reached remotely refuses local sessions with exit code 14; run `thctl` on that machine, or enable user management and use `thctl login`.
+- Local sessions belong to the built-in `Local Operator` account (`local-trust` identity, Admin, all nodes). They appear as regular `cli` sessions that can be listed and revoked in the Control Plane, and account creation plus session minting are audited.
+- Local sessions share the 14-day TTL and revocation semantics and are never renewed through `/api/auth/cli/renew`. When the session expires, is revoked, or is rejected with 401, the CLI clears the credential and mints a new session, continuing the current command. `thctl logout` still revokes the server session and clears the credential; the next command mints a fresh local session while the desktop Control Plane is reachable.
+- If the desktop Control Plane moves to a new port, the managed profile converges to the new loopback origin and records the identity change (`profile show --json` exposes `source` and `identityChangedAt`).
+- Once the Control Plane is switched to `authentication: required`, the local endpoint is rejected and `thctl` falls back to the Web/device authorization flow.
+
+## Command surface
+
+Global options: `--profile <label>`, `--json`, `--yes`, `--dry-run`, `--config <file>`, `--token-stdin`.
+
+| group | commands |
+| --- | --- |
+| `profile` | `add`, `list`, `use`, `show`, `remove`, `trust` |
+| auth | `login`, `logout`, `whoami` |
+| `instance` | `list`, `show`, `create`, `delete`, `start`, `stop`, `restart`, `rename` |
+| `ai-session` | `list`, `show`, `history`, `turns`, `turn`, `timeline`, `turn-timeline`, `create`, `send`, `interrupt`, `approval`, `resume`, `read`, `rename`, `fork`, `close`, `model`, `reasoning`, `queue list`, `queue steer`, `queue retry`, `queue remove`, `queue edit`, `queue reorder` |
+| `app-session` | `list`, `show`, `start`, `stop`, `rename`, `access`, `restart` |
+| `node` | `list`, `show`, `rename`, `create`, `remove`, `check`, `sync-local`, `folders list`, `folders tree`, `folders add`, `folders update`, `folders remove`, `runtimes list`, `runtimes create`, `runtimes update`, `runtimes remove`, `runtimes check`, `docker images`, `image-options`, `settings external-listener show`, `settings external-listener set`, `settings model-relay show`, `settings model-relay set`, `updates jobs`, `updates check`, `updates apply`, `pairing invite`, `pairings list`, `pairings remove`, `connections list`, `connections create`, `connections remove` |
+| `node-join` | `invite`, `status`, `complete` |
+| `story` | `list`, `show`, `create`, `update`, `archive`, `restore`, `remove`, `document update`, `document remove`, `document reorder`, `automation list`, `automation show`, `automation create`, `automation update`, `automation remove`, `automation enable`, `automation disable`, `automation run`, `automation runs` |
+| `trigger` | `list`, `show`, `create`, `update`, `remove`, `run`, `bind`, `unbind`, `apply` |
+| `model` | `list`, `show`, `create`, `copy`, `discover`, `test`, `reorder`, `update`, `sync`, `merge`, `remove`, `node list`, `node create`, `node update`, `node remove`, `node discover`, `node test` |
+| `project` | `list`, `show`, `create`, `update`, `remove` |
+| `image` | `list`, `show`, `create`, `update`, `remove`, `options` |
+| `market` | `catalog`, `refresh` |
+| `env-template` | `list`, `show`, `create`, `remove` |
+| `git-credential` | `list`, `show`, `create`, `update`, `remove`, `assignments list`, `assignments assign`, `assignments unassign` |
+| `chat` | `status`, `bridges list`, `bridges create`, `bridges update`, `bridges start`, `bridges stop`, `bridges remove`, `sessions list`, `sessions show` |
+| `mobile-session` | `list`, `revoke` |
+| `control-plane` | `status`, `settings show`, `settings update`, `diagnostic-logs export` |
+| `cloud` | `show`, `challenge`, `remote-access`, `disconnect` |
+| `proxy` | `invites list`, `invites create`, `invites remove`, `bindings list`, `bindings remove`, `diagnostics`, `pending-claims list`, `pending-claims resume`, `pending-claims remove` |
+| `user` | `list`, `show`, `sessions`, `session-revoke`, `create`, `update`, `access`, `password-reset`, `role list`, `role create`, `role update`, `role remove`, `permission list`, `identity-provider list`, `identity-provider create`, `identity-provider update`, `identity-provider remove`, `external-identity list`, `external-identity approve`, `external-identity reject` |
+| stream | `events` |
+| contract | `schema` |
+
+- Data goes to stdout, diagnostics to stderr; `--json` keeps the server wire field names.
+- `--config <file>` carries a JSON request body for commands whose input is too large for flags (write inputs such as `instance create`, `node create`, `project create`, `image create`, `model create`, `chat bridges create`); the file must parse to a JSON object. `--token-stdin` reads a one-time token from stdin (for example `node-join complete`). Secrets are never accepted as positional arguments, so `--config` and `--token-stdin` are the only secret input channels.
+- Write commands require confirmation. Non-TTY callers must pass `--yes`; `--dry-run` prints the request (or the ordered requests of a multi-step write) without sending it.
+- Exit codes: `0` ok, `2` usage, `3` not implemented, `4` confirmation required, `5` not authenticated, `6` forbidden, `7` not found, `8` conflict, `9` rate limited, `10` network, `11` protocol, `12` server, `13` identity, `14` capability missing, `15` cancelled.
+- `thctl schema [group [leaf]] [--format json|md] [--out <file>]` exports the contract; leaves marked `outputMode: json-lines` stream one JSON document per line.
+- `story automation create|update` read the automation payload from `--config <file>`: the file never carries `storyId` (it comes from the argument) — `create` takes `{ actionId, schedule, enabled?, policy? }`, `update` takes any non-empty subset of `{ actionId, schedule, enabled, policy }`.
+
+### Capability gating
+
+Management commands are gated by the capabilities the target advertises, and a missing capability only closes that one command domain:
+
+- Node-scoped commands (`node check`, `node folders *`, `node runtimes *`, `node docker images`, `node image-options`, `node settings *`, `node updates *`, `node pairing invite`, `node pairings *`, `node connections *`, `node-join *`) query the node's structured capability document from `GET /api/nodes/:id` through the shared `supportsNode*` helpers.
+- Control Plane management commands (`user *`, `control-plane *`, `cloud *`, `proxy *`, `mobile-session *`) query the identity payload's `supportsControlPlane*` helpers (`userManagement`, `customRoles`, `externalIdentityLogin`).
+- A server that predates a route answers with `404`/`405`/`501` without the structured error envelope; the CLI normalizes this to `CLI_CAPABILITY_MISSING` and exits `14`, naming both the command and the capability it required. Login, `whoami`, and commands in domains that are still supported keep working.
+- A protocol-version mismatch is only a warning; it never blocks registration, login, or existing commands.
+
+### Instances
+
+```bash
+thctl instance list --json
+thctl instance show <instanceId> --json
+thctl instance create --config ./instance.json --start
+thctl instance delete <instanceId> --yes
+thctl instance delete <instanceId> --volumes --yes
+
+# ./instance.json：POST /api/controlled-instances 的请求体
+# {
+#   "nodeId": "node_x",
+#   "source": { "type": "local-folder", "path": "/Users/me/project" },
+#   "imageSelection": { "imageId": "img_x" },
+#   "start": true
+# }
+```
+
+- `create` 的 `runtimeId` 省略时服务端用 `runtime_local_docker`；`nodeId` 省略时按 project/服务端默认节点解析；Docker runtime 必须能从 `environmentSource`、`imageSelection` 或 project 默认镜像解析出镜像，否则 400 `RUNTIME_IMAGE_REQUIRED`。
+- 带 `gitCredentialRetention: "instance-retained"` 的创建要求账号具备 `manage-secrets` 权限，否则退出码 6。
+- 创建返回 `startOutcome`：`not-requested`（body 未要求 start）、`started`（已请求启动，Docker 镜像可能仍在 provisioning）、`failed`（已创建但启动失败，错误在 `startOutcome.error`）。
+- `delete` 的 `deleteVolumes` 恒为布尔值：不带 `--volumes` 发送 `false`（卷保留），带 `--volumes` 发送 `true`；删除未完成时命令以退出码 8 结束，`volumeResults` 在错误详情里，重跑同一命令即可重试。
+
+### Nodes, settings, and access
+
+```bash
+# Node inventory and ownership
+thctl node list --json
+thctl node check <nodeId>
+thctl node folders tree <nodeId> --json
+thctl node runtimes list <nodeId> --json
+thctl node docker images <nodeId> --json
+thctl node settings external-listener show <nodeId>
+thctl node updates check <nodeId> --config ./check.json
+thctl node updates apply <nodeId> --config ./rollout.json --wait
+
+# Enroll another machine
+thctl node-join invite --config ./join-invite.json --yes
+thctl node-join status <inviteId>
+thctl node-join complete --config ./join-complete.json --yes
+
+# Catalogs and settings
+thctl project create --config ./project.json --yes
+thctl image list --json
+thctl market catalog --json
+thctl model discover --config ./discover.json
+thctl env-template create <instanceId> --config ./env-template.json --yes
+thctl git-credential create --config ./credential.json --yes
+echo "$GIT_TOKEN" | thctl git-credential create --config ./credential.json --token-stdin --yes
+echo "$NEW_PASSWORD" | thctl user password-reset <userId> --token-stdin --yes
+thctl chat status --json
+thctl control-plane settings show --json
+thctl control-plane diagnostic-logs export --out ./diagnostic-logs.tar.gz
+thctl cloud challenge --json
+
+# Access management
+thctl user create --config ./user.json --yes
+thctl user role list --json
+thctl user identity-provider list --json
+thctl user external-identity approve <approvalId> --yes
+```
+
+- `node updates apply --wait` polls `updates/jobs` until the rollout reaches a terminal state; an interrupted wait exits `15`.
+- `control-plane diagnostic-logs export` streams the archive to `--out` and never prints the payload to stdout.
+- `user create|update|access|password-reset`, `role *`, `identity-provider *`, and `external-identity *` are each independently gated by `userManagement`, `customRoles`, and `externalIdentityLogin`; losing one does not disable `user list|show|sessions`.
+
+## Event stream
+
+```bash
+thctl events
+thctl events --topic ai.sessions --topic instances
+thctl events --topic ai-sessions --instance <instanceId>
+thctl events --json | jq -c 'select(.topic == "instances")'
+```
+
+`thctl events` subscribes to the existing `/api/events` WebSocket with the CLI session bearer token and writes every event envelope as one JSON line (JSON Lines in both default and `--json` mode).
+
+- `--topic` is repeatable; values are protocol topics (for example `ai.sessions`, `app.sessions`, `instances`, `nodes`, `triggers`, `stories`, `models`) or exact event types. The `ai-sessions` and `app-sessions` spellings are accepted as aliases. `--topic` omitted subscribes to `*`.
+- `--instance <instanceId>` scopes the subscription server-side; a scope the account cannot see closes the stream with exit code 6.
+- Transport frames (`streams.hello`, keepalive `pong`) are consumed by the CLI and never printed.
+- The subscription opts into the hierarchical AI Session projection and explicitly disables resource metric snapshots and the high-frequency AI Session transient streams; only authoritative events are printed.
+- Disconnects reconnect with the shared exponential backoff and re-subscribe. Reconnection is snapshot-first: nothing is emitted before the new `streams.hello` handshake completes, and replayed event ids are deduplicated, so consumers never see the same event id twice. The command never falls back to polling.
+- Credential rejection (HTTP 401) clears the stored CLI session and exits 5; an initial connection failure exits 10 instead of retrying forever, while a failure after the first authoritative handshake keeps retrying.
+- `Ctrl+C` closes the stream and exits 0.
+
+## Minimum server version
+
+The Control Plane must be a release that declares the `cliSessions` capability in its public identity document and exposes the CLI authorization and session routes (or, for the local desktop Control Plane, declares `localCliSessions` and exposes `POST /api/auth/cli/local`). Older Control Planes are rejected with exit code 14 before any local state is written. The pinned protocol version is recorded per profile as `YYYY-MM-DD` and shown by `thctl profile show`.

package/bin/thctl

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../dist/thctl.js");