@cotal-ai/pi 0.109.3 → 0.109.4

package/dist/index.js

@@ -9875,6 +9875,10 @@ var OS_ENV_ALLOW = [
   "APPDATA",
   "LOCALAPPDATA",
   "XDG_RUNTIME_DIR",
+  // The usage opt-out and the CI marker other tools read too: a seat's own `cotal` commands then
+  // report, or stay silent, as the run that launched it does (docs/telemetry.md).
+  "DO_NOT_TRACK",
+  "CI",
   // Windows system env. SystemRoot is mandatory: without it a spawned process aborts at startup
   // (node `InitializeOnce`, winsock/ICU can't load) — and a `pty`-runtime (ConPTY) child does NOT
   // inherit it the way a plain child_process does, so a manager-spawned agent dies before its first
@@ -9910,7 +9914,10 @@ var OPERATOR_ENV_KEEP = [
   "COTAL_IDP_TIMEOUT_MS",
   "COTAL_CODEX_BIN",
   "COTAL_OPENCODE_BIN",
-  "COTAL_ORCA_BIN"
+  "COTAL_ORCA_BIN",
+  "COTAL_TELEMETRY",
+  "COTAL_TELEMETRY_DISABLED",
+  "COTAL_TELEMETRY_URL"
 ];
 function launchEnv(opts = {}) {
   for (const k of opts.envAllow ?? []) {
@@ -27449,10 +27456,10 @@ import { isConcreteChannel as isConcreteChannel3, channelInAllow as channelInAll
 import { parsePrincipalKey as parsePrincipalKey2, peerLabel as peerLabel3 } from "@cotal-ai/core";
 
 // ../connector-core/dist/docs-bundle.generated.js
-var DOCS_VERSION = "0.109.3";
+var DOCS_VERSION = "0.109.4";
 function loadDocsBundle() {
   return {
-    "version": "0.109.3",
+    "version": "0.109.4",
     "generatedFrom": "docs/*.md + SPEC.md + spec/cotal-lang.md + spec/cotal.schema.json",
     "pages": [
       {
@@ -27773,7 +27780,7 @@ function loadDocsBundle() {
         "kind": "Reference",
         "category": "Reference",
         "summary": "The cotal CLI sends usage data about commands, failures and platforms.",
-        "body": '# Telemetry\n\n> **Reference** \xB7 **For:** everyone who runs the `cotal` CLI\n\nThe `cotal` CLI sends usage data about commands, failures and platforms. Telemetry is on by\ndefault and works without a mesh or sign-in. Events carry a random install id; at `regular`,\na hashed account identifier can also link usage across machines. You can turn it off with\n`cotal telemetry off`. The field tables below describe the event bodies.\n\n## Levels\n\n| Level | What is sent |\n|---|---|\n| `off` | Nothing. Under the environment opt-outs the settings file is neither read nor created. |\n| `minimal` | One `command` event per command with the command name, outcome, exit code, duration, Cotal version, OS, architecture, Node major and CI flag. |\n| `regular` (default) | The `command` event with the registered subcommand, flag names, typed error code, the failure\'s error text with values and paths masked, whether stdout is a terminal, and the shell and terminal program names; plus one `install` event per UTC day with the installed connectors, extensions, runtimes and mesh count. |\n\n```bash\ncotal telemetry            # the level in force, where it comes from, the install id and the URL\ncotal telemetry off\ncotal telemetry minimal\ncotal telemetry regular    # the default; `on` is an alias\n```\n\nThe environment outranks the file: `DO_NOT_TRACK=1` or `COTAL_TELEMETRY_DISABLED=1` forces `off`,\nand `COTAL_TELEMETRY=off|minimal|regular` names a level. Any other `COTAL_TELEMETRY` value refuses\nwith `USAGE_INVALID`. `cotal telemetry` names the source of the level in force. While the\nenvironment forces `off`, `cotal telemetry <level>` saves nothing and creates no file: it is a\n`no-op` with an `ENVIRONMENT_OPT_OUT` warning. Otherwise `cotal telemetry <level>` is a `no-op` only\nwhen the file already holds that level, so the run that creates the file reports `ok`.\n\nThe settings live in the OS user\'s own Cotal directory, `~/.cotal/telemetry.json`\n(`%LOCALAPPDATA%\\Cotal\\telemetry.json` on Windows), mode `0600`: the level, a random install id\n(uuid v4), the file\'s creation time, and the times of the one-time notice and the last install\nevent. `COTAL_HOME` does not move this file, so every workspace one person runs under their own\naccount reports the same install id. An invalid file is not replaced: a command that reads\ntelemetry settings refuses with `SCHEMA_INVALID`. Environment opt-outs bypass that read.\n\n<a id="never-sent"></a>\n\n## Data boundaries\n\nThe event builders do not collect command argument values, mesh, space, agent, user or host\nnames, prompts or messages. They do collect the environment-derived fields listed below,\nincluding `TERM_PROGRAM` at `regular`. Failure text is sent at `regular` after pattern-based\nmasking (see `errorMessage`); masking is not a guarantee that arbitrary error text contains no\nidentifying information. Use `minimal` to exclude error text or `off` to send nothing.\n\nThe install id is a persistent identifier for the settings file. The `account` field at\n`regular` hashes the cached sign-in\'s IdP URL and subject id; it allows correlation across\nmachines without sending those raw identifiers. The daemon, manager,\nconnectors and workflow runtime send nothing; neither do internal\nentries, hidden daemon runners, `agent-bearer` and `cotal telemetry` itself.\n\nThe intake receives the request\'s IP address even though the CLI does not put it in the\nJSON body. The [website API description](https://cotal.ai/openapi.json) says accepted\nevents are relayed to product analytics. This repository defines the CLI payload and\nopt-outs; it does not establish the receiving service\'s IP handling or retention policy.\n\n## Delivery\n\nOne `command` event is posted as the CLI process exits, whatever the exit path. At `regular`, the\nfirst command of each UTC day also posts an `install` event first. Each is one `POST` of JSON,\n`content-type: application/json`, to `https://cotal.ai/v1/telemetry`. The command and install\nposts share one 1.5 second send deadline, with no retry. Send failures are ignored and do not\nchange the command\'s exit code; the exit hook waits at most 1.5 seconds for delivery. `COTAL_TELEMETRY_URL` points a self-hosted intake. It must be an `http` or\n`https` URL, because a send to anything else fails and that failure is ignored too. Any other value\nrefuses with `USAGE_INVALID` before the command runs whenever the level in force sends events, and\n`cotal telemetry` refuses it at every level, since it reports that URL.\n\nWhen the settings file selects `regular`, the first run with a terminal on stderr prints\none notice and records it. A non-terminal run can send events without printing the notice;\na later terminal run still shows it. An environment-selected level does not trigger that notice.\n\n## The `command` event\n\n| Field | Type | Meaning |\n|---|---|---|\n| `v` | `1` | Body version. |\n| `installId` | uuid string | The install id. |\n| `level` | `"minimal"` or `"regular"` | The level the event was sent at. |\n| `event` | `"command"` | |\n| `command` | string | The registered top-level command name (`up`, `spawn`, `ext`), never a user word. |\n| `outcome` | `"ok"`, `"error"` or `"refused"` | Exit 0 is `ok`; a typed refusal, or exit 2 without one, is `refused`; anything else is `error`. |\n| `exitCode` | integer | The process exit code. |\n| `durationMs` | integer | Milliseconds from dispatch to exit. |\n| `version` | string | The `cotal-ai` version. |\n| `os` | string | `process.platform`. |\n| `arch` | string | `process.arch`. |\n| `node` | integer | The Node major version. |\n| `ci` | boolean | Whether `CI` is set. |\n\nAt `regular` the event also carries:\n\n| Field | Type | Meaning |\n|---|---|---|\n| `account` | string or `null` | A sha256 hash of the IdP URL and subject id of the home\'s cached sign-in, cut to 32 hex characters, so one person counts once across machines; with several sign-ins, the first by IdP URL. `null` without a sign-in. |\n| `subcommand` | string or `null` | The registered subcommand the first positional names (`ext add`, `daemon status`), never a user value. |\n| `flags` | string array, at most 32 | Flag names as typed (`--json`, `-j`, `--server`), values stripped; an unknown flag counts by name. |\n| `errorCode` | string or `null` | The typed code of a refusal or failure (`USAGE_INVALID`, `AUTH_REQUIRED`, `OPERATION_PARTIAL`); `null` on success or when the exit carried no code. |\n| `errorMessage` | string or `null`, at most 500 characters | The failure\'s message after masking: quoted words become `<value>` (the CLI quotes every user value it echoes), URLs `<url>`, email addresses `<email>`, IPv4 addresses `<ip>`, paths `<path>` and any run of 32 or more token characters `<token>`. `null` on success. |\n| `errorStack` | string or `null`, at most 2000 characters | At most 12 frames of the failure\'s stack, each file path cut down to its part inside `node_modules` (the installed package and file, never the directory it is installed under); a frame outside one reads `<path>`. `null` on success or when the failure had no stack. |\n| `interactive` | boolean | Whether stdout is a terminal. |\n| `shell` | string or `null` | The basename of `SHELL`. |\n| `terminal` | string or `null` | `TERM_PROGRAM` as set. |\n\n## The `install` event\n\nSent at `regular` only, at most once per UTC day, before that day\'s first `command` event. It\ncarries `v`, `installId`, `level: "regular"`, `event: "install"`, `version`, `os`, `arch`, `node`\nand `ci` as above, and:\n\n| Field | Type | Meaning |\n|---|---|---|\n| `account` | string or `null` | As in the `command` event. |\n| `osRelease` | string | `os.release()`. |\n| `packageManager` | string or `null` | The agent in `npm_config_user_agent` as `name@major` (`npm@10`, `pnpm@9`), when a package manager ran the command. |\n| `installMethod` | `"installer"`, `"npm"` or `"unknown"` | `installer` under the launcher `get.cotal.ai` writes, `npm` when the binary runs from a `node_modules` tree. |\n| `connectors` | `{ kind, version }` array | The installed connectors by kind (`claude`, `opencode`, `codex`, `hermes`, `jcode`, `pi`), from the extensions manifest. |\n| `extensions` | `{ name, version }` array | The other installed `@cotal-ai/*` packages. Third-party packages are not listed. |\n| `runtimes` | string array | The registered runtime names (`pty`, `tmux`, `cmux`, `orca`, `herdr`). |\n| `meshes` | integer | How many meshes the mesh registry holds. |\n| `hostedMesh` | boolean | Whether any registered mesh uses user sign-in. |\n| `uptimeDays` | integer | Whole days since `telemetry.json` was created. |\n'
+        "body": '# Telemetry\n\n> **Reference** \xB7 **For:** everyone who runs the `cotal` CLI\n\nThe `cotal` CLI sends usage data about commands, failures and platforms. Telemetry is on by\ndefault and works without a mesh or sign-in. Events carry a random install id; at `regular`,\na hashed account identifier can also link usage across machines. You can turn it off with\n`cotal telemetry off`. The field tables below describe the event bodies.\n\n## Levels\n\n| Level | What is sent |\n|---|---|\n| `off` | Nothing. Under the environment opt-outs the settings file is neither read nor created. |\n| `minimal` | One `command` event per command with the command name, outcome, exit code, duration, Cotal version, OS, architecture, Node major and CI flag. |\n| `regular` (default) | The `command` event with the registered subcommand, flag names, typed error code, the failure\'s error text with values and paths masked, whether stdout is a terminal, and the shell and terminal program names; plus one `install` event per UTC day with the installed connectors, extensions, runtimes and mesh count. |\n\n```bash\ncotal telemetry            # the level in force, where it comes from, the install id and the URL\ncotal telemetry off\ncotal telemetry minimal\ncotal telemetry regular    # the default; `on` is an alias\n```\n\nThe environment outranks the file: `DO_NOT_TRACK=1` or `COTAL_TELEMETRY_DISABLED=1` forces `off`,\nand `COTAL_TELEMETRY=off|minimal|regular` names a level. Any other `COTAL_TELEMETRY` value refuses\nwith `USAGE_INVALID`. `cotal telemetry` names the source of the level in force. While the\nenvironment forces `off`, `cotal telemetry <level>` saves nothing and creates no file: it is a\n`no-op` with an `ENVIRONMENT_OPT_OUT` warning. Otherwise `cotal telemetry <level>` is a `no-op` only\nwhen the file already holds that level, so the run that creates the file reports `ok`.\n\nThese variables, `COTAL_TELEMETRY_URL` and `CI` reach the processes Cotal starts from the environment\nthat sets them: the daemons, the services `cotal service start` launches and the agents a manager\nspawns. A `cotal` command one of them runs therefore reports, or stays off, as the command that\nstarted it would. A seat a running manager launches carries the manager\'s environment, not that of\nthe `cotal spawn` that asked for it, and a service your login starts after `cotal service install`\ncarries its unit\'s. `cotal telemetry off` is in the file every one of them reads.\n\nThe settings live in the OS user\'s own Cotal directory, `~/.cotal/telemetry.json`\n(`%LOCALAPPDATA%\\Cotal\\telemetry.json` on Windows), mode `0600`: the level, a random install id\n(uuid v4), the file\'s creation time, and the times of the one-time notice and the last install\nevent. `COTAL_HOME` does not move this file, so every workspace one person runs under their own\naccount reports the same install id, across upgrades and git worktrees too. An invalid file is not\nreplaced: a command that reads telemetry settings refuses with `SCHEMA_INVALID`. Environment\nopt-outs bypass that read. Deleting the file resets the install id: the next command creates a new\none.\n\nA home without the file gets a new install id on its first command, so the id cannot persist where\nthe home does not: a new OS user, a fresh CI runner, a container whose home is not on a volume. An\nimage build that runs a `cotal` command bakes its file, and one install id, into every container\nstarted from the image, so run those commands with `DO_NOT_TRACK=1`, as `deploy/docker` does.\n\n<a id="never-sent"></a>\n\n## Data boundaries\n\nThe event builders do not collect command argument values, mesh, space, agent, user or host\nnames, prompts or messages. They do collect the environment-derived fields listed below,\nincluding `TERM_PROGRAM` at `regular`. Failure text is sent at `regular` after pattern-based\nmasking (see `errorMessage`); masking is not a guarantee that arbitrary error text contains no\nidentifying information. Use `minimal` to exclude error text or `off` to send nothing.\n\nThe install id is a persistent identifier for the settings file. The `account` field at\n`regular` hashes the cached sign-in\'s IdP URL and subject id; it allows correlation across\nmachines without sending those raw identifiers. The daemon, manager,\nconnectors and workflow runtime send nothing; neither do internal\nentries, hidden daemon runners, `agent-bearer` and `cotal telemetry` itself.\n\nThe intake receives the request\'s IP address even though the CLI does not put it in the\nJSON body. The [website API description](https://cotal.ai/openapi.json) says accepted\nevents are relayed to product analytics. This repository defines the CLI payload and\nopt-outs; it does not establish the receiving service\'s IP handling or retention policy.\n\n## Delivery\n\nOne `command` event is posted as the CLI process exits, whatever the exit path. At `regular`, the\nfirst command of each UTC day also posts an `install` event first. Each is one `POST` of JSON,\n`content-type: application/json`, to `https://cotal.ai/v1/telemetry`. The command and install\nposts share one 1.5 second send deadline, with no retry. Send failures are ignored and do not\nchange the command\'s exit code; the exit hook waits at most 1.5 seconds for delivery. `COTAL_TELEMETRY_URL` points a self-hosted intake. It must be an `http` or\n`https` URL, because a send to anything else fails and that failure is ignored too. Any other value\nrefuses with `USAGE_INVALID` before the command runs whenever the level in force sends events, and\n`cotal telemetry` refuses it at every level, since it reports that URL.\n\nWhen the settings file selects `regular`, the first run with a terminal on stderr prints\none notice and records it. A non-terminal run can send events without printing the notice;\na later terminal run still shows it. An environment-selected level does not trigger that notice.\n\n## The `command` event\n\n| Field | Type | Meaning |\n|---|---|---|\n| `v` | `1` | Body version. |\n| `installId` | uuid string | The install id. |\n| `level` | `"minimal"` or `"regular"` | The level the event was sent at. |\n| `event` | `"command"` | |\n| `command` | string | The registered top-level command name (`up`, `spawn`, `ext`), never a user word. |\n| `outcome` | `"ok"`, `"error"` or `"refused"` | Exit 0 is `ok`; a typed refusal, or exit 2 without one, is `refused`; anything else is `error`. |\n| `exitCode` | integer | The process exit code. |\n| `durationMs` | integer | Milliseconds from dispatch to exit. |\n| `version` | string | The `cotal-ai` version. |\n| `os` | string | `process.platform`. |\n| `arch` | string | `process.arch`. |\n| `node` | integer | The Node major version. |\n| `ci` | boolean | Whether `CI` is set to anything but `0` or `false`. |\n\nAt `regular` the event also carries:\n\n| Field | Type | Meaning |\n|---|---|---|\n| `account` | string or `null` | A sha256 hash of the IdP URL and subject id of the home\'s cached sign-in, cut to 32 hex characters, so one person counts once across machines; with several sign-ins, the first by IdP URL. `null` without a sign-in. It is read as the command starts, so a `login` reports the sign-in cached before it and a `logout` the one it removes. |\n| `subcommand` | string or `null` | The registered subcommand the first positional names (`ext add`, `daemon status`), never a user value. |\n| `flags` | string array, at most 32 | Flag names as typed (`--json`, `-j`, `--server`), values stripped; an unknown flag counts by name. |\n| `errorCode` | string or `null` | The typed code of a refusal or failure (`USAGE_INVALID`, `AUTH_REQUIRED`, `OPERATION_PARTIAL`); `null` on success or when the exit carried no code. |\n| `errorMessage` | string or `null`, at most 500 characters | The failure\'s message after masking: quoted words become `<value>` (the CLI quotes every user value it echoes), URLs `<url>`, email addresses `<email>`, IPv4 addresses `<ip>`, paths `<path>` and any run of 32 or more token characters `<token>`. `null` on success. |\n| `errorStack` | string or `null`, at most 2000 characters | At most 12 frames of the failure\'s stack, each file path cut down to its part inside `node_modules` (the installed package and file, never the directory it is installed under); a frame outside one reads `<path>`. `null` on success or when the failure had no stack. |\n| `interactive` | boolean | Whether stdout is a terminal. |\n| `shell` | string or `null` | The basename of `SHELL`. |\n| `terminal` | string or `null` | `TERM_PROGRAM` as set. |\n\n## The `install` event\n\nSent at `regular` only, at most once per UTC day, before that day\'s first `command` event. It\ncarries `v`, `installId`, `level: "regular"`, `event: "install"`, `version`, `os`, `arch`, `node`\nand `ci` as above, and:\n\n| Field | Type | Meaning |\n|---|---|---|\n| `account` | string or `null` | As in the `command` event. |\n| `osRelease` | string | `os.release()`. |\n| `packageManager` | string or `null` | The agent in `npm_config_user_agent` as `name@major` (`npm@10`, `pnpm@9`), when a package manager ran the command. |\n| `installMethod` | `"installer"`, `"npm"` or `"unknown"` | `installer` under the launcher `get.cotal.ai` writes, `npm` when the binary runs from a `node_modules` tree. |\n| `connectors` | `{ kind, version }` array | The installed connectors by kind (`claude`, `opencode`, `codex`, `hermes`, `jcode`, `pi`), from the extensions manifest. |\n| `extensions` | `{ name, version }` array | The other installed `@cotal-ai/*` packages. Third-party packages are not listed. |\n| `runtimes` | string array | The registered runtime names (`pty`, `tmux`, `cmux`, `orca`, `herdr`). |\n| `meshes` | integer | How many meshes the mesh registry holds. |\n| `hostedMesh` | boolean | Whether any registered mesh uses user sign-in. |\n| `uptimeDays` | integer | Whole days since `telemetry.json` was created. |\n'
       },
       {
         "slug": "transport",

package/dist/standalone.js

@@ -65927,10 +65927,10 @@ function date4(params) {
 config(en_default());
 
 // ../connector-core/dist/docs-bundle.generated.js
-var DOCS_VERSION = "0.109.3";
+var DOCS_VERSION = "0.109.4";
 function loadDocsBundle() {
   return {
-    "version": "0.109.3",
+    "version": "0.109.4",
     "generatedFrom": "docs/*.md + SPEC.md + spec/cotal-lang.md + spec/cotal.schema.json",
     "pages": [
       {
@@ -66251,7 +66251,7 @@ function loadDocsBundle() {
         "kind": "Reference",
         "category": "Reference",
         "summary": "The cotal CLI sends usage data about commands, failures and platforms.",
-        "body": '# Telemetry\n\n> **Reference** \xB7 **For:** everyone who runs the `cotal` CLI\n\nThe `cotal` CLI sends usage data about commands, failures and platforms. Telemetry is on by\ndefault and works without a mesh or sign-in. Events carry a random install id; at `regular`,\na hashed account identifier can also link usage across machines. You can turn it off with\n`cotal telemetry off`. The field tables below describe the event bodies.\n\n## Levels\n\n| Level | What is sent |\n|---|---|\n| `off` | Nothing. Under the environment opt-outs the settings file is neither read nor created. |\n| `minimal` | One `command` event per command with the command name, outcome, exit code, duration, Cotal version, OS, architecture, Node major and CI flag. |\n| `regular` (default) | The `command` event with the registered subcommand, flag names, typed error code, the failure\'s error text with values and paths masked, whether stdout is a terminal, and the shell and terminal program names; plus one `install` event per UTC day with the installed connectors, extensions, runtimes and mesh count. |\n\n```bash\ncotal telemetry            # the level in force, where it comes from, the install id and the URL\ncotal telemetry off\ncotal telemetry minimal\ncotal telemetry regular    # the default; `on` is an alias\n```\n\nThe environment outranks the file: `DO_NOT_TRACK=1` or `COTAL_TELEMETRY_DISABLED=1` forces `off`,\nand `COTAL_TELEMETRY=off|minimal|regular` names a level. Any other `COTAL_TELEMETRY` value refuses\nwith `USAGE_INVALID`. `cotal telemetry` names the source of the level in force. While the\nenvironment forces `off`, `cotal telemetry <level>` saves nothing and creates no file: it is a\n`no-op` with an `ENVIRONMENT_OPT_OUT` warning. Otherwise `cotal telemetry <level>` is a `no-op` only\nwhen the file already holds that level, so the run that creates the file reports `ok`.\n\nThe settings live in the OS user\'s own Cotal directory, `~/.cotal/telemetry.json`\n(`%LOCALAPPDATA%\\Cotal\\telemetry.json` on Windows), mode `0600`: the level, a random install id\n(uuid v4), the file\'s creation time, and the times of the one-time notice and the last install\nevent. `COTAL_HOME` does not move this file, so every workspace one person runs under their own\naccount reports the same install id. An invalid file is not replaced: a command that reads\ntelemetry settings refuses with `SCHEMA_INVALID`. Environment opt-outs bypass that read.\n\n<a id="never-sent"></a>\n\n## Data boundaries\n\nThe event builders do not collect command argument values, mesh, space, agent, user or host\nnames, prompts or messages. They do collect the environment-derived fields listed below,\nincluding `TERM_PROGRAM` at `regular`. Failure text is sent at `regular` after pattern-based\nmasking (see `errorMessage`); masking is not a guarantee that arbitrary error text contains no\nidentifying information. Use `minimal` to exclude error text or `off` to send nothing.\n\nThe install id is a persistent identifier for the settings file. The `account` field at\n`regular` hashes the cached sign-in\'s IdP URL and subject id; it allows correlation across\nmachines without sending those raw identifiers. The daemon, manager,\nconnectors and workflow runtime send nothing; neither do internal\nentries, hidden daemon runners, `agent-bearer` and `cotal telemetry` itself.\n\nThe intake receives the request\'s IP address even though the CLI does not put it in the\nJSON body. The [website API description](https://cotal.ai/openapi.json) says accepted\nevents are relayed to product analytics. This repository defines the CLI payload and\nopt-outs; it does not establish the receiving service\'s IP handling or retention policy.\n\n## Delivery\n\nOne `command` event is posted as the CLI process exits, whatever the exit path. At `regular`, the\nfirst command of each UTC day also posts an `install` event first. Each is one `POST` of JSON,\n`content-type: application/json`, to `https://cotal.ai/v1/telemetry`. The command and install\nposts share one 1.5 second send deadline, with no retry. Send failures are ignored and do not\nchange the command\'s exit code; the exit hook waits at most 1.5 seconds for delivery. `COTAL_TELEMETRY_URL` points a self-hosted intake. It must be an `http` or\n`https` URL, because a send to anything else fails and that failure is ignored too. Any other value\nrefuses with `USAGE_INVALID` before the command runs whenever the level in force sends events, and\n`cotal telemetry` refuses it at every level, since it reports that URL.\n\nWhen the settings file selects `regular`, the first run with a terminal on stderr prints\none notice and records it. A non-terminal run can send events without printing the notice;\na later terminal run still shows it. An environment-selected level does not trigger that notice.\n\n## The `command` event\n\n| Field | Type | Meaning |\n|---|---|---|\n| `v` | `1` | Body version. |\n| `installId` | uuid string | The install id. |\n| `level` | `"minimal"` or `"regular"` | The level the event was sent at. |\n| `event` | `"command"` | |\n| `command` | string | The registered top-level command name (`up`, `spawn`, `ext`), never a user word. |\n| `outcome` | `"ok"`, `"error"` or `"refused"` | Exit 0 is `ok`; a typed refusal, or exit 2 without one, is `refused`; anything else is `error`. |\n| `exitCode` | integer | The process exit code. |\n| `durationMs` | integer | Milliseconds from dispatch to exit. |\n| `version` | string | The `cotal-ai` version. |\n| `os` | string | `process.platform`. |\n| `arch` | string | `process.arch`. |\n| `node` | integer | The Node major version. |\n| `ci` | boolean | Whether `CI` is set. |\n\nAt `regular` the event also carries:\n\n| Field | Type | Meaning |\n|---|---|---|\n| `account` | string or `null` | A sha256 hash of the IdP URL and subject id of the home\'s cached sign-in, cut to 32 hex characters, so one person counts once across machines; with several sign-ins, the first by IdP URL. `null` without a sign-in. |\n| `subcommand` | string or `null` | The registered subcommand the first positional names (`ext add`, `daemon status`), never a user value. |\n| `flags` | string array, at most 32 | Flag names as typed (`--json`, `-j`, `--server`), values stripped; an unknown flag counts by name. |\n| `errorCode` | string or `null` | The typed code of a refusal or failure (`USAGE_INVALID`, `AUTH_REQUIRED`, `OPERATION_PARTIAL`); `null` on success or when the exit carried no code. |\n| `errorMessage` | string or `null`, at most 500 characters | The failure\'s message after masking: quoted words become `<value>` (the CLI quotes every user value it echoes), URLs `<url>`, email addresses `<email>`, IPv4 addresses `<ip>`, paths `<path>` and any run of 32 or more token characters `<token>`. `null` on success. |\n| `errorStack` | string or `null`, at most 2000 characters | At most 12 frames of the failure\'s stack, each file path cut down to its part inside `node_modules` (the installed package and file, never the directory it is installed under); a frame outside one reads `<path>`. `null` on success or when the failure had no stack. |\n| `interactive` | boolean | Whether stdout is a terminal. |\n| `shell` | string or `null` | The basename of `SHELL`. |\n| `terminal` | string or `null` | `TERM_PROGRAM` as set. |\n\n## The `install` event\n\nSent at `regular` only, at most once per UTC day, before that day\'s first `command` event. It\ncarries `v`, `installId`, `level: "regular"`, `event: "install"`, `version`, `os`, `arch`, `node`\nand `ci` as above, and:\n\n| Field | Type | Meaning |\n|---|---|---|\n| `account` | string or `null` | As in the `command` event. |\n| `osRelease` | string | `os.release()`. |\n| `packageManager` | string or `null` | The agent in `npm_config_user_agent` as `name@major` (`npm@10`, `pnpm@9`), when a package manager ran the command. |\n| `installMethod` | `"installer"`, `"npm"` or `"unknown"` | `installer` under the launcher `get.cotal.ai` writes, `npm` when the binary runs from a `node_modules` tree. |\n| `connectors` | `{ kind, version }` array | The installed connectors by kind (`claude`, `opencode`, `codex`, `hermes`, `jcode`, `pi`), from the extensions manifest. |\n| `extensions` | `{ name, version }` array | The other installed `@cotal-ai/*` packages. Third-party packages are not listed. |\n| `runtimes` | string array | The registered runtime names (`pty`, `tmux`, `cmux`, `orca`, `herdr`). |\n| `meshes` | integer | How many meshes the mesh registry holds. |\n| `hostedMesh` | boolean | Whether any registered mesh uses user sign-in. |\n| `uptimeDays` | integer | Whole days since `telemetry.json` was created. |\n'
+        "body": '# Telemetry\n\n> **Reference** \xB7 **For:** everyone who runs the `cotal` CLI\n\nThe `cotal` CLI sends usage data about commands, failures and platforms. Telemetry is on by\ndefault and works without a mesh or sign-in. Events carry a random install id; at `regular`,\na hashed account identifier can also link usage across machines. You can turn it off with\n`cotal telemetry off`. The field tables below describe the event bodies.\n\n## Levels\n\n| Level | What is sent |\n|---|---|\n| `off` | Nothing. Under the environment opt-outs the settings file is neither read nor created. |\n| `minimal` | One `command` event per command with the command name, outcome, exit code, duration, Cotal version, OS, architecture, Node major and CI flag. |\n| `regular` (default) | The `command` event with the registered subcommand, flag names, typed error code, the failure\'s error text with values and paths masked, whether stdout is a terminal, and the shell and terminal program names; plus one `install` event per UTC day with the installed connectors, extensions, runtimes and mesh count. |\n\n```bash\ncotal telemetry            # the level in force, where it comes from, the install id and the URL\ncotal telemetry off\ncotal telemetry minimal\ncotal telemetry regular    # the default; `on` is an alias\n```\n\nThe environment outranks the file: `DO_NOT_TRACK=1` or `COTAL_TELEMETRY_DISABLED=1` forces `off`,\nand `COTAL_TELEMETRY=off|minimal|regular` names a level. Any other `COTAL_TELEMETRY` value refuses\nwith `USAGE_INVALID`. `cotal telemetry` names the source of the level in force. While the\nenvironment forces `off`, `cotal telemetry <level>` saves nothing and creates no file: it is a\n`no-op` with an `ENVIRONMENT_OPT_OUT` warning. Otherwise `cotal telemetry <level>` is a `no-op` only\nwhen the file already holds that level, so the run that creates the file reports `ok`.\n\nThese variables, `COTAL_TELEMETRY_URL` and `CI` reach the processes Cotal starts from the environment\nthat sets them: the daemons, the services `cotal service start` launches and the agents a manager\nspawns. A `cotal` command one of them runs therefore reports, or stays off, as the command that\nstarted it would. A seat a running manager launches carries the manager\'s environment, not that of\nthe `cotal spawn` that asked for it, and a service your login starts after `cotal service install`\ncarries its unit\'s. `cotal telemetry off` is in the file every one of them reads.\n\nThe settings live in the OS user\'s own Cotal directory, `~/.cotal/telemetry.json`\n(`%LOCALAPPDATA%\\Cotal\\telemetry.json` on Windows), mode `0600`: the level, a random install id\n(uuid v4), the file\'s creation time, and the times of the one-time notice and the last install\nevent. `COTAL_HOME` does not move this file, so every workspace one person runs under their own\naccount reports the same install id, across upgrades and git worktrees too. An invalid file is not\nreplaced: a command that reads telemetry settings refuses with `SCHEMA_INVALID`. Environment\nopt-outs bypass that read. Deleting the file resets the install id: the next command creates a new\none.\n\nA home without the file gets a new install id on its first command, so the id cannot persist where\nthe home does not: a new OS user, a fresh CI runner, a container whose home is not on a volume. An\nimage build that runs a `cotal` command bakes its file, and one install id, into every container\nstarted from the image, so run those commands with `DO_NOT_TRACK=1`, as `deploy/docker` does.\n\n<a id="never-sent"></a>\n\n## Data boundaries\n\nThe event builders do not collect command argument values, mesh, space, agent, user or host\nnames, prompts or messages. They do collect the environment-derived fields listed below,\nincluding `TERM_PROGRAM` at `regular`. Failure text is sent at `regular` after pattern-based\nmasking (see `errorMessage`); masking is not a guarantee that arbitrary error text contains no\nidentifying information. Use `minimal` to exclude error text or `off` to send nothing.\n\nThe install id is a persistent identifier for the settings file. The `account` field at\n`regular` hashes the cached sign-in\'s IdP URL and subject id; it allows correlation across\nmachines without sending those raw identifiers. The daemon, manager,\nconnectors and workflow runtime send nothing; neither do internal\nentries, hidden daemon runners, `agent-bearer` and `cotal telemetry` itself.\n\nThe intake receives the request\'s IP address even though the CLI does not put it in the\nJSON body. The [website API description](https://cotal.ai/openapi.json) says accepted\nevents are relayed to product analytics. This repository defines the CLI payload and\nopt-outs; it does not establish the receiving service\'s IP handling or retention policy.\n\n## Delivery\n\nOne `command` event is posted as the CLI process exits, whatever the exit path. At `regular`, the\nfirst command of each UTC day also posts an `install` event first. Each is one `POST` of JSON,\n`content-type: application/json`, to `https://cotal.ai/v1/telemetry`. The command and install\nposts share one 1.5 second send deadline, with no retry. Send failures are ignored and do not\nchange the command\'s exit code; the exit hook waits at most 1.5 seconds for delivery. `COTAL_TELEMETRY_URL` points a self-hosted intake. It must be an `http` or\n`https` URL, because a send to anything else fails and that failure is ignored too. Any other value\nrefuses with `USAGE_INVALID` before the command runs whenever the level in force sends events, and\n`cotal telemetry` refuses it at every level, since it reports that URL.\n\nWhen the settings file selects `regular`, the first run with a terminal on stderr prints\none notice and records it. A non-terminal run can send events without printing the notice;\na later terminal run still shows it. An environment-selected level does not trigger that notice.\n\n## The `command` event\n\n| Field | Type | Meaning |\n|---|---|---|\n| `v` | `1` | Body version. |\n| `installId` | uuid string | The install id. |\n| `level` | `"minimal"` or `"regular"` | The level the event was sent at. |\n| `event` | `"command"` | |\n| `command` | string | The registered top-level command name (`up`, `spawn`, `ext`), never a user word. |\n| `outcome` | `"ok"`, `"error"` or `"refused"` | Exit 0 is `ok`; a typed refusal, or exit 2 without one, is `refused`; anything else is `error`. |\n| `exitCode` | integer | The process exit code. |\n| `durationMs` | integer | Milliseconds from dispatch to exit. |\n| `version` | string | The `cotal-ai` version. |\n| `os` | string | `process.platform`. |\n| `arch` | string | `process.arch`. |\n| `node` | integer | The Node major version. |\n| `ci` | boolean | Whether `CI` is set to anything but `0` or `false`. |\n\nAt `regular` the event also carries:\n\n| Field | Type | Meaning |\n|---|---|---|\n| `account` | string or `null` | A sha256 hash of the IdP URL and subject id of the home\'s cached sign-in, cut to 32 hex characters, so one person counts once across machines; with several sign-ins, the first by IdP URL. `null` without a sign-in. It is read as the command starts, so a `login` reports the sign-in cached before it and a `logout` the one it removes. |\n| `subcommand` | string or `null` | The registered subcommand the first positional names (`ext add`, `daemon status`), never a user value. |\n| `flags` | string array, at most 32 | Flag names as typed (`--json`, `-j`, `--server`), values stripped; an unknown flag counts by name. |\n| `errorCode` | string or `null` | The typed code of a refusal or failure (`USAGE_INVALID`, `AUTH_REQUIRED`, `OPERATION_PARTIAL`); `null` on success or when the exit carried no code. |\n| `errorMessage` | string or `null`, at most 500 characters | The failure\'s message after masking: quoted words become `<value>` (the CLI quotes every user value it echoes), URLs `<url>`, email addresses `<email>`, IPv4 addresses `<ip>`, paths `<path>` and any run of 32 or more token characters `<token>`. `null` on success. |\n| `errorStack` | string or `null`, at most 2000 characters | At most 12 frames of the failure\'s stack, each file path cut down to its part inside `node_modules` (the installed package and file, never the directory it is installed under); a frame outside one reads `<path>`. `null` on success or when the failure had no stack. |\n| `interactive` | boolean | Whether stdout is a terminal. |\n| `shell` | string or `null` | The basename of `SHELL`. |\n| `terminal` | string or `null` | `TERM_PROGRAM` as set. |\n\n## The `install` event\n\nSent at `regular` only, at most once per UTC day, before that day\'s first `command` event. It\ncarries `v`, `installId`, `level: "regular"`, `event: "install"`, `version`, `os`, `arch`, `node`\nand `ci` as above, and:\n\n| Field | Type | Meaning |\n|---|---|---|\n| `account` | string or `null` | As in the `command` event. |\n| `osRelease` | string | `os.release()`. |\n| `packageManager` | string or `null` | The agent in `npm_config_user_agent` as `name@major` (`npm@10`, `pnpm@9`), when a package manager ran the command. |\n| `installMethod` | `"installer"`, `"npm"` or `"unknown"` | `installer` under the launcher `get.cotal.ai` writes, `npm` when the binary runs from a `node_modules` tree. |\n| `connectors` | `{ kind, version }` array | The installed connectors by kind (`claude`, `opencode`, `codex`, `hermes`, `jcode`, `pi`), from the extensions manifest. |\n| `extensions` | `{ name, version }` array | The other installed `@cotal-ai/*` packages. Third-party packages are not listed. |\n| `runtimes` | string array | The registered runtime names (`pty`, `tmux`, `cmux`, `orca`, `herdr`). |\n| `meshes` | integer | How many meshes the mesh registry holds. |\n| `hostedMesh` | boolean | Whether any registered mesh uses user sign-in. |\n| `uptimeDays` | integer | Whole days since `telemetry.json` was created. |\n'
       },
       {
         "slug": "transport",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cotal-ai/pi",
-  "version": "0.109.3",
+  "version": "0.109.4",
   "license": "Apache-2.0",
   "keywords": [
     "cotal",
@@ -34,8 +34,8 @@
     "@earendil-works/pi-tui": ">=0.79.10"
   },
   "devDependencies": {
-    "@cotal-ai/core": "0.109.3",
-    "@cotal-ai/connector-core": "0.109.3",
+    "@cotal-ai/core": "0.109.4",
+    "@cotal-ai/connector-core": "0.109.4",
     "@cotal-ai/smoke-kit": "0.0.0",
     "@earendil-works/pi-ai": "0.79.10",
     "@earendil-works/pi-coding-agent": "0.79.10",