@harnessforce/cli 0.0.0-bootstrap.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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/README.md

@@ -0,0 +1,271 @@
+# @harnessforce/cli
+
+`harnessforce`, the command line of [Harnessforce](https://github.com/lambda-script/harnessforce-agent). It
+connects a machine to a Harnessforce Workspace, supplies the ingest key to Claude Code's OpenTelemetry
+exporter, launches an agent linked to an Issue, and imports the metadata of past Claude Code sessions.
+
+It is used together with the `harnessforce` Claude Code plugin, whose `/harnessforce:setup` installs
+it. Public distribution on npm starts once the production domain of Harnessforce is decided; until
+then, install it from the [local marketplace build](https://github.com/lambda-script/harnessforce-agent/blob/main/docs/runbooks/local-marketplace.md).
+
+## Requirements
+
+- Node.js 18 or later (the same Node.js the plugin hook uses).
+- An OS keychain: macOS Keychain, the Secret Service on Linux, or the Windows Credential Manager.
+  Keys and tokens are never written to a plain file.
+
+## Install
+
+```sh
+npm install -g @harnessforce/cli
+harnessforce init
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `harnessforce init [--url <base URL>] [--port <port>] [--send-content]` | Logs in with the browser, stores a user ingest key and an API token in the keychain, and configures Claude Code and Codex |
+| `harnessforce otel-headers` | Prints the `Authorization` header for Claude Code's `otelHeadersHelper` |
+| `harnessforce run --issue <identifier> -- <agent> [args]` | Launches an agent with its session linked to an Issue |
+| `harnessforce import` | Sends the metadata of past Claude Code sessions in connected repositories |
+| `harnessforce tune [--all] [--no-send] [--show-report] [--json]` | Analyzes past sessions on this machine by public rules and sends the counts (analysis reports) |
+| `harnessforce tune record` / `harnessforce tune --purge` | Records a proposal from stdin / deletes everything under `~/.harnessforce/tune/` |
+| `harnessforce top [--once] [--json] [--ascii] [--theme <auto\|light\|dark\|ansi>]` | Shows the Claude Code and Codex sessions on this machine in the terminal: state, tokens, context and tool failures. Reads only local files and never connects to Harnessforce |
+| `harnessforce hook session-start` | The entry of Codex's `SessionStart` hook: reads `session_id`, `cwd` and `source` from stdin, registers the session, and prints the session ID for the agent's context. Always exits 0 |
+| `harnessforce usage-limits on [--yes]` / `off` / `status` | Shares your usage limits with the workspace after you agree to the consent text (`on`), or withdraws the consent, deletes the stored values and restores your previous statusLine (`off`), or shows the consent, the workspace opt-in and whether the statusLine is wrapped (`status`). Not supported on Windows |
+| `harnessforce usage-limits statusline` | A statusLine command that wraps your existing one: it passes stdin to the original command, returns its output and exit code unchanged, then sends only the usage percentage and reset time of the 5-hour and 7-day windows. It sends nothing until you have consented |
+| `harnessforce --version` | Prints the version |
+
+## Watching your sessions (`harnessforce top`)
+
+`harnessforce top` reads the Claude Code transcripts on this machine (the same place as `harnessforce import`) and the
+Codex rollouts (`sessions/YYYY/MM/DD/rollout-*.jsonl` under `$CODEX_HOME` when it is an absolute path, otherwise
+`~/.codex`) and shows one row per session whose last event is within 24 hours. It needs no `harnessforce init`, makes no network
+connection, never reads the keychain and writes nothing to disk. It shows counts, times, ids, the repository and
+branch, model and tool names only: no prompt, response, tool input or output, path, command or error text, no cost and
+no context percentage.
+
+- The `agent` column says `claude` or `codex`; `--json` uses `claude_code` or `codex`. For Codex, the tool failure
+  count is blank (`tool_failures` is `null`) because Codex does not save whether a call succeeded; the tool column
+  shows the call count only. Rollouts compressed to `.jsonl.zst` (Codex does this after 7 days) and
+  `archived_sessions` are not read.
+- A session is `active` when its last event is within 60 seconds, otherwise `idle`.
+- Keys: `q` quit, `?` help, `↑` `↓` / `j` `k` select, `Enter` detail, `Esc` back, `/` filter, `s` order, `p` pause, `r` refresh.
+- `--once` prints one plain-text table (no escapes). `--json` prints `{"sessions": [...]}`. A pipe or redirect behaves like `--once`.
+- `--ascii` draws with ASCII characters only.
+- The terminal background is never painted. Colors are foreground only, so a symbol and its label always carry the
+  meaning. `--theme auto` asks the terminal for its background once (100 ms limit); when it answers, the colors of the
+  Harnessforce web design system are used, and any color with less than 3:1 contrast on that background is left out.
+  Without an answer, or with `--theme ansi`, the terminal's own 16 colors are used. `NO_COLOR` turns colors off.
+- The screen restores the alternate screen and the cursor on `q`, Ctrl-C, SIGTERM, SIGHUP and a normal exit. A console that does not understand VT escape sequences is not detected: use `--once` or `--ascii` there.
+- `~/.harnessforce/config.json` may set `{"top": {"ambiguous_width": 2, "braille": true}}`. An unreadable file or a
+  value out of range falls back to the defaults and says so; the file is never written.
+
+## Codex `SessionStart` hook (`harnessforce hook session-start`)
+
+Codex runs this command through the `[[hooks.SessionStart]]` entry that `harnessforce init` writes into Codex's
+`config.toml`. It uses only `session_id`, `cwd` and `source` from the JSON on stdin, and:
+
+- sends the session registration (`agent` is `codex`) only when `source` is `startup`, `clear` or missing, and
+  only to the ingest origin that `harnessforce init` pinned, with the user ingest key from the keychain. The
+  Workspace and the endpoint come from `HARNESSFORCE_WORKSPACE_ID` and `HARNESSFORCE_ENDPOINT`, or from the
+  Claude Code user settings that `harnessforce init` wrote. When `HARNESSFORCE_ISSUE` is a valid identifier
+  (`harnessforce run --issue` sets it), the registration claims `source=cli` with that Issue.
+- prints `{"hookSpecificOutput": {...}}` carrying `harnessforce session_id: <id>` so the agent knows its session
+  ID. When the key was revoked (401) it prints that line and the message as plain text instead, and writes the
+  message to stderr.
+- never fails the session: any error ends with exit code 0, and nothing is sent outside a git repository.
+
+## Usage limits in the statusLine (`harnessforce usage-limits statusline`)
+
+Claude Code passes the plan limits (`rate_limits`) only to the statusLine command, not to hooks. `harnessforce usage-limits statusline` is meant to sit in front of the statusLine you already use (for example claude-hud):
+
+- It reads all of stdin and, if `~/.harnessforce/usage-limits.json` has an `original` command, runs it with `sh -c`, hands it the same stdin and the same environment, and returns its stdout, stderr and exit code as they are. No time limit is added.
+- After that, only if `usage-limits.json` records your consent for the current text version, it takes `rate_limits.five_hour` and `rate_limits.seven_day` (`used_percentage` and `resets_at`) and sends them to `POST <ingest endpoint>/v1/usage-limits` with the user ingest key from the keychain. Nothing else in the JSON (`cwd`, `transcript_path`, `cost`, and so on) is read or sent.
+- The send runs in a detached child process with stdin, stdout and stderr closed, so the statusLine is never delayed. A failure does not change the output or the exit code.
+- It sends at most once every 5 minutes, unless the reset time of a window changed. The time and the reset times of the last send are kept in `~/.harnessforce/usage-limits-state.json` (owner-only).
+
+### Turning it on and off
+
+`harnessforce usage-limits on` shows the consent text, asks `y` (skipped with `--yes`), records the consent (`PUT /api/v1/cli/usage-limits/consent`), and then wraps the `statusLine` in your Claude Code user settings: only `command` is replaced with `harnessforce usage-limits statusline`, so `type`, `padding`, `refreshInterval` and the other keys stay. The statusLine you had (for example claude-hud) is saved as-is in `~/.harnessforce/usage-limits.json`. If the statusLine is not `type: "command"`, or the settings cannot be read, nothing is recorded or changed. If writing the mark or the settings fails, the consent is withdrawn again. `harnessforce usage-limits off` withdraws the consent first and then puts the saved statusLine back (or removes it if there was none); a statusLine that another tool has changed since is left alone.
+
+## What is never sent
+
+Harnessforce never turns on prompt or body logging by itself. `harnessforce run` never turns it on, and `harnessforce init`
+adds `OTEL_LOG_USER_PROMPTS=1` to the Claude Code user settings only with `--send-content`, and only
+when the credentials response says the Workspace has opted in to content. Without that, prompts,
+responses, tool inputs and outputs, and file contents are not sent. For a Workspace that has not opted
+in, `harnessforce init --send-content` leaves the setting alone, prints the reason, and still exits 0. `harnessforce run`
+never puts the user key or the API token in the agent's environment, arguments or settings. Keys and
+tokens are sent only to the origins pinned by `harnessforce init`.
+
+## CLI credentials (`harnessforce init`, `harnessforce otel-headers`)
+
+`harnessforce init [--url <base URL>] [--port <port>] [--send-content]` connects this machine to a Harnessforce Workspace:
+
+1. It checks the OS keychain first: macOS Keychain, the Secret Service on Linux, or the Windows
+   Credential Manager (through [`@napi-rs/keyring`](https://github.com/Brooooooklyn/keyring-node)).
+   Without one it stops. Keys are never written to a plain file.
+2. It logs in with the browser: OAuth 2.0 authorization code with PKCE, a `127.0.0.1:8080` loopback
+   redirect (`--port <port>` changes the port), the endpoint discovered from
+   `/.well-known/oauth-authorization-server`, and a 5 minute wait. When the port is already in use it
+   stops instead of moving to another port. If the browser cannot be opened, it prints the URL.
+3. It asks `POST <base URL>/api/v1/cli/credentials` for a user ingest key and an API token (a 1 hour
+   access token and a 90 day refresh token). It also sends the SHA-256 hashes of the ingest keys and of
+   the API tokens' refresh tokens already in the keychain (at most 100 of each), so the old key and
+   token for the chosen Workspace on this machine are revoked. Keys and tokens on other machines stay
+   valid.
+4. It stores both under the keychain service `harnessforce` as `<workspace_id>:ingest-key` and
+   `<workspace_id>:api-token` (a JSON object with the access token, the refresh token and their
+   expiries), and pins the ingest endpoint origin as `<workspace_id>:ingest-origin`
+   and the base URL origin as `<workspace_id>:url-origin`. It deletes both origins first and writes
+   them last, so a failure part way never pairs an old origin with a new key or token.
+5. It updates the Claude Code user settings (`~/.claude/settings.json`, or `$CLAUDE_CONFIG_DIR`),
+   changing only these keys:
+   - `env`: the OTel exporter variables, `HARNESSFORCE_URL`, `HARNESSFORCE_ENDPOINT` and
+     `HARNESSFORCE_WORKSPACE_ID`, but no key. With `--send-content` and a Workspace that has opted in
+     to content it also adds `OTEL_LOG_USER_PROMPTS=1`
+   - `otelHeadersHelper`: `harnessforce otel-headers`
+   - `enabledPlugins["harnessforce@harnessforce-agent"]`
+6. It updates the Codex `config.toml` (`$CODEX_HOME` when it is an absolute path, otherwise `~/.codex`),
+   changing only these three items and keeping every other key and comment:
+   - `[otel].exporter`: OTLP/HTTP (`protocol = "binary"`) to the ingest endpoint with
+     `Authorization = "Bearer <user ingest key>"`. Codex cannot take the header from a command or expand
+     `${VAR}`, so this is the one place a key is written to a plain file. It is the user ingest key only
+     (never the API token), and you can revoke it on the Workspace's send keys page. With `--send-content`
+     and a Workspace that has opted in to content it also sets `log_user_prompt = true`
+   - `[[hooks.SessionStart]]`: a handler that runs `harnessforce hook session-start`
+   - `[mcp_servers.harnessforce]`: `url = "<base URL>/mcp"`
+
+   The file is written through a temporary file in the same directory and renamed into place, with mode
+   `0600`. Running `harnessforce init` again replaces only these three items. Restart Codex afterwards,
+   trust the hook with `/hooks` (Codex runs an untrusted hook only after you review it), and run
+   `codex mcp login harnessforce` to use the MCP server.
+
+`harnessforce otel-headers` prints `{"Authorization":"Bearer <key>"}`. The key is `HARNESSFORCE_INGEST_KEY` from
+the managed settings file when that is set, and otherwise the user key for
+`HARNESSFORCE_WORKSPACE_ID` from the keychain. If
+there is no key, it prints nothing and exits 1. The user key is printed only when every destination
+variable that is set (`HARNESSFORCE_ENDPOINT`, `OTEL_EXPORTER_OTLP_ENDPOINT` and the per-signal
+`OTEL_EXPORTER_OTLP_*_ENDPOINT`) has the pinned origin. This stops a repository's
+`.claude/settings.json` `env` from pointing the hook at another host to collect the key. Otherwise it
+writes `harnessforce: user key withheld (destination not verified)` to stderr and exits 1. Run
+`harnessforce init` again to re-pin.
+
+### Refreshing the API token
+
+`harnessforce import` and `harnessforce run --issue` call the Read API with the access token. When it has expired, or the
+Read API answers 401 once, they take `~/.harnessforce/token.lock`, read the keychain again (another
+process may have refreshed already), and exchange the refresh token at the `token_endpoint` from the
+authorization server metadata of the base URL, only when that endpoint is on the pinned base URL
+origin. The new pair replaces `<workspace_id>:api-token`. A lock older than 60 seconds is treated as
+abandoned, and waiting more than 30 seconds for it counts as a failed refresh. If the refresh fails, or
+the refreshed token is also answered with 401, they stop with
+「ログインの有効期限が切れました。`harnessforce init`を実行してください」.
+
+### Default connection
+
+The default base URL is an optional build input: `HARNESSFORCE_BUILD_URL=<apps/web base URL> pnpm build`.
+Without it the default is `https://harnessforce.dev`. The value must be `https:`, or `http:` for localhost.
+At run time the base URL is the environment variable `HARNESSFORCE_URL`, then `env.HARNESSFORCE_URL` in the
+user settings (`harnessforce init --url` writes it), then the build default. The plugin build
+uses the same value for its MCP server URL. See
+[Building the local marketplace](https://github.com/lambda-script/harnessforce-agent/blob/main/docs/runbooks/local-marketplace.md).
+
+## Launching an agent for an Issue (`harnessforce run`)
+
+`harnessforce run --issue <identifier> -- <agent> [args]` links the session to an Issue before it starts:
+
+1. It reads the Read API base URL (`HARNESSFORCE_URL`, then `env.HARNESSFORCE_URL` in the Claude Code user
+   settings, then the build default), the ingest endpoint (`HARNESSFORCE_ENDPOINT`, then the user
+   settings) and the Workspace (`HARNESSFORCE_WORKSPACE_ID`, then the user settings). Before sending
+   anything it checks, in order: the keychain, the Workspace, its user key, the ingest endpoint and its
+   scheme, the ingest origin pinned by `harnessforce init`, the API token, the Read API scheme, and the Read API
+   origin pinned by `harnessforce init`. The first failed check stops it, usually asking you to run `harnessforce init`.
+2. It resolves the Issue with `GET /api/v1/issues/{identifier}` and the stored API token. If the Issue
+   does not exist, it prints up to 10 candidates from `GET /api/v1/issues?query=<identifier>` and stops.
+3. It computes the config snapshot ID locally with the same collection as the SessionStart hook.
+4. It starts the agent with `HARNESSFORCE_WORKSPACE_ID`, `HARNESSFORCE_ENDPOINT`,
+   `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`, telemetry and traces
+   enabled, `HARNESSFORCE_ISSUE`, and `OTEL_RESOURCE_ATTRIBUTES` carrying `hf.issue.identifier`,
+   `hf.vcs.repository`, `hf.vcs.branch`, `hf.vcs.commit` and `hf.agent.config_version`. It removes
+   `OTEL_EXPORTER_OTLP_HEADERS` and the per-signal `*_HEADERS`, `*_ENDPOINT` and `*_PROTOCOL` variables
+   inherited from the shell. The user key and the API token are never put in the agent's environment,
+   arguments or settings: Claude Code gets the key only through `otelHeadersHelper` (`harnessforce otel-headers`).
+5. For Claude Code (`claude`), the same values also go in a settings file passed as
+   `--settings <absolute path>` before your arguments, because settings files can override the shell.
+   The file is created with mode 0600 in the temp directory and deleted when the agent exits.
+   `HARNESSFORCE_ISSUE` tells the plugin hook to register the session with `source=cli`.
+   For Codex (`codex`, `codex.exe`, `codex.cmd`), only `HARNESSFORCE_WORKSPACE_ID`, `HARNESSFORCE_ENDPOINT` and
+   `HARNESSFORCE_ISSUE` are set, and no settings file is passed. Codex does not read `CLAUDE_CODE_*` or
+   `OTEL_RESOURCE_ATTRIBUTES`, and an `OTEL_EXPORTER_OTLP_ENDPOINT` would replace the endpoint of the `[otel]`
+   exporter that `harnessforce init` writes into Codex's `config.toml`, so the request could go out without its
+   header. The Issue is linked by the Codex `SessionStart` hook, which reads `HARNESSFORCE_ISSUE`. The variables
+   of your own shell are left as they are for Codex.
+6. The agent is found on `PATH` (with `PATHEXT` on Windows), or used as given when the command contains a
+   path separator. On Windows, `.cmd` and `.bat` files (such as npm's `claude.cmd`) are started through
+   `%ComSpec% /d /s /c` with every argument quoted; arguments containing `"`, `%`, `!` or a newline are
+   refused.
+
+It exits with the agent's exit code. Prompt and body logging are never turned on.
+
+## Importing past sessions (`harnessforce import`)
+
+`harnessforce import` sends metadata of past Claude Code sessions on this machine to Harnessforce, so that
+work done before the plugin was installed can be linked to issues too. Run `harnessforce init` first.
+
+- It reads the transcripts in `~/.claude/projects/<project>/<session>.jsonl` (or
+  `$CLAUDE_CONFIG_DIR/projects`). Their format is not documented, so the parser is versioned
+  (`parser_version`), and unreadable lines and files are skipped and counted.
+- Only these values are sent: session ID, first prompt ID, start and end time, repository, branch,
+  the most used model, input and output token counts (without cache tokens), and the number of calls
+  and failures per tool. Prompts, responses and tool inputs and outputs are never sent.
+- Only sessions whose `cwd` is in a repository connected to the Workspace are sent. The connected
+  repositories come from `GET <HARNESSFORCE_URL>/api/v1/repositories` (all pages) and the import
+  window from `session_import_days` (`GET <HARNESSFORCE_URL>/api/v1/workspace`), both with the API
+  token. The API token is sent only when the origin of `HARNESSFORCE_URL` matches the one pinned by
+  `harnessforce init`; otherwise nothing is sent and it asks you to run `harnessforce init`.
+- Sessions are sent 100 at a time to `POST <HARNESSFORCE_ENDPOINT>/v1/imports/sessions` with the user
+  ingest key, only when the endpoint origin matches the one pinned by `harnessforce init`. `429` and `503` are
+  retried up to 3 times after `Retry-After` (at most 60 seconds).
+- Sent sessions are recorded in `~/.harnessforce/import-state.json` per Workspace and ingest endpoint,
+  so running it again continues where it stopped and never sends a session twice to the same place.
+  Sessions dropped because of the monthly event limit or a read-only Workspace are not recorded and
+  are sent by a later run.
+
+The Workspace, the connection URL and the ingest endpoint come from `HARNESSFORCE_WORKSPACE_ID`,
+`HARNESSFORCE_URL` and `HARNESSFORCE_ENDPOINT` in the environment, and otherwise from the `env` that
+`harnessforce init` wrote to the Claude Code user settings.
+
+## Analyzing past sessions (`harnessforce tune`)
+
+`harnessforce tune` reads the same transcripts as `harnessforce import` and turns each session into an analysis report:
+interventions, loops that could be automated, and MCP server calls. Run `harnessforce init` first. The Viewer
+role cannot use it.
+
+- The categories come from public rules and a public vocabulary (`src/tune/analyze.ts`,
+  `src/tune/vocabulary.ts`, `analyzer_version`), never from a model. Categories the transcript cannot
+  tell apart (`approval`, `answer`) are reported as not measured, never as 0.
+- Only the counts and medians of the analysis report are sent, to
+  `POST <HARNESSFORCE_ENDPOINT>/v1/analysis-reports` with the user ingest key. Prompts, responses,
+  commands, paths and error text never leave the machine.
+- By default it analyzes sessions started in the last 30 days in connected repositories. `--all`
+  analyzes every session, but still sends only sessions in connected repositories that started within
+  `session_import_days`. Sessions without a Run are imported first, like `harnessforce import`.
+- Sending is fail-open: when Harnessforce cannot be reached, the reports stay in
+  `~/.harnessforce/tune/unsent.json` and are sent by the next run. `401` and `403` delete the unsent
+  reports and ask you to run `harnessforce init`.
+- `--no-send`, or `{"tune": {"send_report": false}}` in `~/.harnessforce/config.json`, sends nothing.
+  A config file it cannot read also sends nothing.
+- It also counts usage per session (auto and manual context compactions, responses, cache reuse
+  ratio, output tokens per model in the main and subagent transcripts). These values are shown and
+  written to `--json` and `~/.harnessforce/tune/analysis.json` only; they are never sent.
+- `--json` also lists, for each recorded proposal whose application was detected, the value of its
+  category in the 14 days before and after the detection time (`followups`). The difference is not
+  a cause. Once a `--json` run outputs a follow-up whose after period has ended, later runs omit it.
+- Everything it keeps is under `~/.harnessforce/tune/`; `harnessforce tune --purge` deletes it.
+
+## License
+
+[Apache-2.0](https://github.com/lambda-script/harnessforce-agent/blob/main/LICENSE)