impel-cli 0.20.45 → 0.20.46-beta.0

package/README.md

@@ -525,15 +525,148 @@ Main paths:
 ~/.config/impel/config.json
 ~/.config/impel/cli/tenants/<tenant>/
 ~/.config/impel/apps/tenants/<tenant>/
+~/.config/impel/update-check.json
+~/.config/impel/flags.json
+~/.config/impel/telemetry-notice.json
+~/.config/impel/telemetry/
+~/.config/impel/reports/
 ```
 
 The config directory is owner-only and the config file is written with mode
 `0600` where supported. Generated client profiles use tenant-bound helper
 invocations; PAT material is not embedded into shell entries.
 
+`flags.json` caches server-evaluated feature flags for the current principal.
+`telemetry/` holds queued analytics events waiting to be sent, plus their
+send state; it is empty unless analytics are on. `reports/` holds bug reports
+that could not be delivered, kept so they are never lost, bounded to the last
+50 and nothing older than 30 days; its hidden `.last-auto-report.json` records
+what this machine last reported automatically, so the same failure is not
+reported twice in a day. Everything above lives under one directory, so
+`impel nuke` erases all of it.
+
 Losing membership does not delete local tenant data. A future cleanup feature
 must remain explicit and destructive-state aware.
 
+## Privacy
+
+Analytics are off unless you turn them on: nothing in the first table below is
+sent until `telemetry.enabled` is `true` in `config.json`, which only
+`impel setup --analytics on` writes.
+
+Failure reports are the one exception and are described in their own section
+further down. When `impel setup` or `impel update` runs out of ways to fix a
+failure, the CLI files a bug report about that failure whether or not analytics
+are on. That is deliberate: a broken install cannot be fixed by people who never
+hear about it, and the machines least likely to opt in are the ones failing.
+
+**Usage analytics** (`cli_command_run`, one per command, sent when enabled):
+
+| Field | Example | Notes |
+|---|---|---|
+| `command` | `claude` | The command name only — never its arguments |
+| `outcome` | `success` | `success`, `failure`, or `refused` |
+| `durationBucket` | `lt_5s` | A coarse bucket, not a duration |
+| `cliVersion` | `0.20.41` | |
+| `channel` | `latest` | npm release channel |
+| `platform` | `darwin` | `darwin`, `linux`, `win32`, or `unknown` |
+
+**Bug reports** (`cli_bug_report`, one per delivered report): the same
+`cliVersion`, `channel`, and `platform`, plus whether a message was attached,
+whether a task was filed, and if not, why.
+
+Events are identified by the account your PAT resolves to, stamped by the
+server. Nothing else is collected: no command arguments, file contents,
+prompts, session content, environment variables, paths, or credentials. Events
+are validated against a closed allowlist before they reach disk, and anything
+that still looks like a secret after redaction is dropped locally and reported
+by `impel status`.
+
+Events are queued on disk and sent by a detached background process, so no
+command ever waits on the network. Analytics never initialize inside a managed
+desktop app profile or a non-interactive surface.
+
+**Turning analytics off.** Any one of these is enough, and each overrides a
+stored `yes`:
+
+```sh
+IMPEL_DISABLE_TELEMETRY=1 impel claude   # also accepts true/yes
+DO_NOT_TRACK=1 impel claude
+```
+
+Any non-empty `CI` value suppresses analytics as well. To change the stored
+answer, run `impel setup --analytics off`. To erase everything already queued,
+run `impel nuke`.
+
+## Automatic failure reports
+
+When `impel setup` or `impel update` fails in a way it cannot recover from, the
+CLI files a bug report about that failure and prints one line saying so, with
+the report's id and how to turn the behavior off. It does not ask first.
+
+**What triggers one.** Only a terminal failure of `impel setup` or `impel
+update` — a failure that recovery already tried and could not repair. A failure
+that recovery fixes is not a failure, and reports nothing. No other command
+reports itself, and a successful run never reports.
+
+**What is in it.** The same fields `impel report` sends, assembled from what the
+command already had in hand:
+
+| Field | Example | Notes |
+|---|---|---|
+| `message` | `The npm-verified global impel-cli update failed.` | Written by the CLI, not by you |
+| `cliVersion` | `0.20.41` | |
+| `nodeVersion` | `v22.11.0` | |
+| `platform` | `darwin` | |
+| `architecture` | `arm64` | |
+| `channel` | `latest` | npm release channel |
+| `command` | `npm install --global impel-cli` | The command that failed, when there was one |
+| `exitCode` | `1` | |
+| `errorCode` | `install_failed` | |
+| `stderr` | | That command's output, redacted |
+| `diagnostics` | `{ "step": "install.impel_cli", "reportId": "…" }` | The failing step, the report id, and a handful of scalars naming what the run was doing |
+
+Credentials, home directory paths, and email addresses are removed before
+anything leaves the machine, by the same redaction the manual command uses.
+Nothing else is collected: no arguments beyond the failing command line, no file
+contents, no prompts, no session content, no environment variables.
+
+**Turning it off.** Either of these, and only these:
+
+```sh
+IMPEL_DO_NOT_TRACK=1 impel setup
+IMPEL_CI=1 impel setup
+```
+
+Bare `DO_NOT_TRACK` and bare `CI` **do not** suppress failure reports, though
+they still suppress analytics. The two surfaces have different contracts on
+purpose: `CI` is set by every CI runner on earth and says nothing about whether
+its operators want to hear that installs are broken there, and deciding that for
+them is how a broken install stays broken. Suppressing a failure report takes
+the branded name, typed on purpose.
+
+The consequence is worth stating plainly: a GitHub Actions job sets `CI=true`,
+not `IMPEL_CI`, so a repeatedly failing `impel setup` in an unmodified CI
+pipeline files a report every run until someone sets `IMPEL_CI=1`.
+
+Reports are also suppressed when the CLI is a rebranded distribution, when it
+runs inside a managed desktop app profile, and when there is no PAT to attribute
+the report to.
+
+**The same failure is not reported twice in a day.** The report id is a
+fingerprint of the report's own contents, so an identical failure produces an
+identical id; `~/.config/impel/reports/.last-auto-report.json` records what was
+reported and when, and a repeat inside 24 hours is dropped silently.
+
+**Delivery is best effort and never blocks.** Two retries against an unreachable
+control plane, then the report is written to `~/.config/impel/reports/` like any
+other undelivered report. A reporting failure never changes the exit code of the
+command that failed, and never adds a second error message to the one you
+already got.
+
+`impel report` remains a message you choose to send: neither switch above
+disables it, and it works whether or not analytics are on.
+
 ## Public command surface
 
 ```text
@@ -548,6 +681,7 @@ impel tasks ...
 impel pat ...
 impel status
 impel doctor
+impel report
 ```
 
 Profile helpers, content synchronization, desktop maintenance, and transport

package/docs/native-agent-host-capability-matrix.md

@@ -1,6 +1,6 @@
 # Native-agent host capability matrix
 
-Validated on 2026-08-09 with isolated temporary homes and tenant profiles. The
+Validated on 2026-08-11 with isolated temporary homes and tenant profiles. The
 matrix is intentionally pinned: a client upgrade must be re-qualified before it
 is treated as an eager host.
 
@@ -9,7 +9,7 @@ is treated as an eager host.
 | Claude Code | 2.1.220 | Yes, agent frontmatter `tools` | Eager; optional single-thread selection | The bound run/answer, resume, and recovery tools are direct child tools. `impel claude --agent` verifies the exact managed adapter before enabling 2.1.220's bypass-permission opt-in and mode. |
 | Claude Desktop | 1.26832.0 (embedded Code 2.1.222) | Yes, agent frontmatter `tools` | Eager | Same direct-tool contract as Claude Code. |
 | Codex CLI through `impel codex` | 0.147.0 | Yes, with `features.code_mode.direct_only_tool_namespaces = ["mcp__impel_agent"]` | Eager; optional single-thread profile | Existing `@Agent` children call the fixed MCP namespace directly. `impel codex --agent` also removes the parent spawn/wait/relay thread. |
-| ChatGPT desktop Codex | 26.803.41515 (embedded Codex 0.147.0-alpha.6.5) | Yes, with the same exact native namespace | Eager child, compatible parent | Keeps the app's supported `@Agent` parent/child route, but the child no longer needs code cells or code-mode waits. |
+| ChatGPT desktop Codex | 26.803.81509 (embedded Codex 0.147.0-alpha.6.6) | Yes, with the same exact native namespace | Eager child, compatible parent | Keeps the app's supported `@Agent` parent/child route, but the child no longer needs code cells or code-mode waits. |
 
 ## Qualified contract
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.20.45",
+  "version": "0.20.46-beta.0",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {

package/src/apps.js

@@ -107,8 +107,8 @@ export const PINNED_VENDOR_APPS = Object.freeze({
     }),
   }),
   chatgpt: Object.freeze({
-    version: "26.803.41515",
-    codexVersion: "0.147.0-alpha.6.5",
+    version: "26.803.81509",
+    codexVersion: "0.147.0-alpha.6.6",
     bundleName: "ChatGPT.app",
     windows: Object.freeze({
       storeProductId: "9PLM9XGG6VKS",
@@ -116,20 +116,20 @@ export const PINNED_VENDOR_APPS = Object.freeze({
       // The Microsoft Store manifest identifies this exact reviewed build.
       // Keep one Windows package version so the manifest contract and local
       // AppX validation cannot silently drift apart again.
-      packageVersion: "26.803.5235.0",
-      codexVersion: "0.147.0-alpha.6.5",
+      packageVersion: "26.803.10989.0",
+      codexVersion: "0.147.0-alpha.6.6",
       publisherId: "2p2nqsd0c76g0",
       executable: "app\\ChatGPT.exe",
       updateManifestUrl: "https://persistent.oaistatic.com/codex-app-prod/windows-store-update.json",
     }),
     downloads: Object.freeze({
       arm64: Object.freeze({
-        url: "https://persistent.oaistatic.com/codex-app-prod/ChatGPT-darwin-arm64-26.803.41515.zip",
-        sha256: "8abd46bf063bc27cbadcbc2863007ac44365b13a23ede17ceaee81fb9eeaeb9a",
+        url: "https://persistent.oaistatic.com/codex-app-prod/ChatGPT-darwin-arm64-26.803.81509.zip",
+        sha256: "34c7e629678ad5d63a639ec694a5b83b85f4e1bd7c21ee2abcfefbb041095b9c",
       }),
       x64: Object.freeze({
-        url: "https://persistent.oaistatic.com/codex-app-prod/ChatGPT-darwin-x64-26.803.41515.zip",
-        sha256: "87239a3dd12e2761de515ee78a0b73c02ac907c34c1f01a68dd6f093cf433fb1",
+        url: "https://persistent.oaistatic.com/codex-app-prod/ChatGPT-darwin-x64-26.803.81509.zip",
+        sha256: "c9d5a14803c3138a77be5e891a4944c04ff421645150043dd3eddd0bf34eda97",
       }),
     }),
   }),

package/src/autoReport.js

@@ -0,0 +1,289 @@
+// The automatic bug-report path: a failed `impel setup` or `impel update`
+// reporting itself.
+//
+// The manual command in `src/commands/report.js` has a person attached — they
+// typed it, they are watching, and an error they can read is a useful outcome.
+// This module has none of that. It runs inside a command that has already
+// failed, on a machine whose owner may have walked away, and the only two
+// things it owes anyone are the disclosure line and a promise never to make the
+// failure worse. Everything below follows from that asymmetry:
+//
+//   - Every gate returns silently. There is no "reporting was skipped because…"
+//     sentence, because nobody asked for a report and a refusal is not news.
+//   - The whole body is wrapped in a `try`/`catch` that swallows (KTD10). A
+//     throw from here would surface as a crash inside a command that had
+//     already decided how it wanted to fail.
+//   - `process.exitCode` is never written. The failing command owns its exit
+//     code; the report is a side effect, not an outcome.
+//
+// What is *sent* is identical to the manual path — same `buildEnvelope`, same
+// origin check, same spool — because "the automatic sender cannot send
+// something the manual sender would not" has to be a property of the code
+// rather than a habit. This file only decides *whether* to send.
+//
+// The suppression marker lives under `CONFIG_DIR`, so `impel nuke` erases it.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  buildEnvelope,
+  deliverWithRetry,
+  MAX_DIAGNOSTIC_KEYS,
+  REPORT_SPOOL_DIR,
+  resolveReportOrigin,
+  sleep,
+  spoolReport,
+  writeJsonAtomically,
+} from "./bugReport.js";
+import { resolveDefaultAppUrl } from "./config.js";
+import { fetchHttp1 } from "./http1.js";
+import { sanitizeInstallFailureEnvelope } from "./installRecovery/redact.js";
+import {
+  DO_NOT_TRACK_ENV,
+  firstPartyCli,
+  managedMarkerPresent,
+  reportEnvOptOut,
+} from "./telemetryConsent.js";
+
+/**
+ * Shorter than `impel report`'s 10 s: this timeout is spent by a command that
+ * has already failed and wants to exit. Three attempts at 5 s plus 500/1,500 ms
+ * of backoff is ~17 s worst case against a black hole (KTD5).
+ */
+export const AUTO_REPORT_TIMEOUT_MS = 5_000;
+
+/** R4's record of what this machine has already reported. */
+export const AUTO_REPORT_MARKER_NAME = ".last-auto-report.json";
+
+/**
+ * The marker sits beside the spooled reports rather than in its own directory,
+ * so one `impel nuke` erases both and a test that redirects `spoolDir`
+ * redirects the marker with it.
+ */
+export function autoReportMarkerPath(spoolDir = REPORT_SPOOL_DIR) {
+  return path.join(spoolDir, AUTO_REPORT_MARKER_NAME);
+}
+
+/** R4's window. A failure that recurs the next day is worth hearing about again. */
+export const AUTO_REPORT_SUPPRESSION_MS = 24 * 60 * 60 * 1_000;
+
+/**
+ * A list, not a single slot (KTD4). One machine reaches more than one failure
+ * mode, and two alternating failures sharing a slot would evict each other's
+ * record so neither is ever suppressed — the exact case automatic dispatch
+ * makes common.
+ */
+export const AUTO_REPORT_MARKER_ENTRIES = 32;
+
+/**
+ * `buildEnvelope` adds `tenant` and `reportId` of its own, and this mapping adds
+ * four more, so the failure's own diagnostics are trimmed to leave room.
+ * Exceeding `MAX_DIAGNOSTIC_KEYS` throws, and a report lost to a crowded
+ * diagnostics bag is a worse outcome than a report missing its 19th diagnostic.
+ */
+const RESERVED_DIAGNOSTIC_KEYS = 6;
+
+/* -------------------------------------------------------------------------- */
+/* Envelope                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Fold the sanitized install-failure envelope into the bug-report field bag.
+ *
+ * The two shapes are close enough to look interchangeable and are not.
+ * `bugReportEnvelopeSchema` is `.strict()`, so `scope`, `tenantId`, `step`, and
+ * `signal` have no top-level home and must travel inside `diagnostics`. Each
+ * mismatch left uncorrected is a 400, not a dropped field.
+ *
+ * The wire's own bounds are not re-applied here: `buildEnvelope` already
+ * truncates each field to its schema length and drops a falsy one rather than
+ * sending it, which is the same answer the sanitizer's `null`s want. A second
+ * copy of `64` in this file would be a bound that can drift from the one the
+ * server actually enforces.
+ *
+ * `step` doubles as `command` when the failure has none, so the server's task
+ * title has something to name.
+ */
+function reportFields(sanitized) {
+  const own = Object.entries(sanitized.diagnostics || {})
+    .slice(0, MAX_DIAGNOSTIC_KEYS - RESERVED_DIAGNOSTIC_KEYS);
+  return {
+    message: sanitized.message,
+    command: sanitized.command || sanitized.step,
+    errorCode: sanitized.errorCode,
+    exitCode: sanitized.exitCode,
+    log: sanitized.stderr || sanitized.stdout || "",
+    diagnostics: {
+      ...Object.fromEntries(own),
+      scope: sanitized.scope,
+      step: sanitized.step,
+      ...(sanitized.tenantId ? { tenantId: sanitized.tenantId } : {}),
+      ...(sanitized.signal ? { signal: sanitized.signal } : {}),
+    },
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Suppression marker                                                         */
+/* -------------------------------------------------------------------------- */
+
+/** An unreadable or malformed marker reads as absent: it must not block a report. */
+function readMarker(markerPath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(markerPath, "utf8"));
+    if (!Array.isArray(parsed?.entries)) return [];
+    return parsed.entries.filter((entry) => (
+      entry && typeof entry.reportId === "string" && typeof entry.sentAt === "string"
+    ));
+  } catch {
+    return [];
+  }
+}
+
+function alreadyReported(entries, reportId, now) {
+  return entries.some((entry) => {
+    if (entry.reportId !== reportId) return false;
+    const sentAt = Date.parse(entry.sentAt);
+    return Number.isFinite(sentAt) && now - sentAt < AUTO_REPORT_SUPPRESSION_MS;
+  });
+}
+
+/**
+ * Record this send.
+ *
+ * Losing the marker costs one duplicate report; refusing to report because the
+ * marker could not be written costs the report. So every failure here is
+ * swallowed by the caller.
+ */
+function writeMarker(markerPath, entries, reportId, now) {
+  const kept = entries
+    .filter((entry) => entry.reportId !== reportId)
+    .filter((entry) => {
+      const sentAt = Date.parse(entry.sentAt);
+      return Number.isFinite(sentAt) && now - sentAt < AUTO_REPORT_SUPPRESSION_MS;
+    });
+  // Newest first, so the cap drops the oldest.
+  const next = [{ reportId, sentAt: new Date(now).toISOString() }, ...kept]
+    .slice(0, AUTO_REPORT_MARKER_ENTRIES);
+  writeJsonAtomically(markerPath, { entries: next });
+}
+
+/* -------------------------------------------------------------------------- */
+/* Dispatch                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * File a bug report for a failed install, or do nothing.
+ *
+ * `failure` is the same object the command already hands `io.recoverInstall`,
+ * so a call site adds no new data collection — it hands over what it had
+ * assembled anyway.
+ *
+ * `io` is the *calling command's* bag, which carries none of the delivery
+ * seams: `impel setup` and `impel update` have no `fetchImpl`, no `spoolDir`,
+ * no `sleep`. Those defaults are supplied here and caller keys win, so a test
+ * can inject a fake fetch and a command does not have to grow twelve fields it
+ * has no other use for.
+ */
+export async function reportInstallFailure({ failure, config, io = {} }) {
+  try {
+    const environment = io.environment || process.env;
+    const homeDir = io.homeDir || os.homedir();
+
+    // KTD2's order. `firstPartyCli` leads: a rebranded fork must not inherit
+    // Impel's phone-home, and that answer does not depend on this machine's
+    // config, environment, or PAT — so it is also the only gate that can be
+    // decided without reading any of them.
+    if (!firstPartyCli()) return;
+    if (reportEnvOptOut(environment)) return;
+    // Before the marker check only because it is a property read and that one
+    // walks `realpath` up the ancestor chain. Nothing to authenticate with is
+    // just as final an answer, and this is a command that has already failed
+    // and wants to exit.
+    if (!config?.pat) return;
+    // Not a consent question (R7): a managed vendor app profile may reach the
+    // gateway and nothing else, so a report from inside one presents as an
+    // unexpected egress call from a profile holding app credentials.
+    if (managedMarkerPresent(environment, homeDir)) return;
+
+    const delivery = {
+      environment,
+      homeDir,
+      fetchImpl: fetchHttp1,
+      spoolDir: REPORT_SPOOL_DIR,
+      timeoutMs: AUTO_REPORT_TIMEOUT_MS,
+      now: Date.now(),
+      platform: process.platform,
+      sleep,
+      log: console.log,
+      warn: console.warn,
+      ...io,
+    };
+
+    // The same destination the manual command resolves, through the same
+    // check, for the same reason and one more: this sender has no user to
+    // notice that `appUrl` was hand-edited. A rejection is a gate like any
+    // other and returns silently — there is no `--app` flag to correct.
+    let appUrl;
+    try {
+      appUrl = resolveReportOrigin(config.appUrl || resolveDefaultAppUrl());
+    } catch {
+      return;
+    }
+
+    // Sanitize first, then build — not instead of building. The sanitizer
+    // removes credentials, home paths, and emails from the recovery envelope;
+    // `buildEnvelope` is what makes it a wire-legal bug report.
+    const sanitized = sanitizeInstallFailureEnvelope(failure, { homeDir });
+    const { envelope, reportId } = buildEnvelope({
+      fields: reportFields(sanitized),
+      config,
+      io: delivery,
+    });
+
+    // R4. Read before printing: a suppressed report prints nothing at all,
+    // because the disclosure line exists to explain a send that is happening.
+    const markerPath = autoReportMarkerPath(delivery.spoolDir);
+    const entries = readMarker(markerPath);
+    if (alreadyReported(entries, reportId, delivery.now)) return;
+
+    // R9/KTD6: before the request, and worded as an attempt. The id is a
+    // fingerprint of the envelope so it is already known, and up to ~17 s of
+    // retries against an unreachable control plane should not be a silent
+    // pause. A past-tense claim would be false in exactly the case that
+    // matters — a spooled report announcing a send that never happened.
+    delivery.log(`Reporting this failure automatically (id ${reportId}). Set ${DO_NOT_TRACK_ENV}=1 to disable.`);
+
+    const { outcome } = await deliverWithRetry({
+      envelope,
+      appUrl,
+      currentPat: config.pat,
+      io: delivery,
+    });
+
+    if (!outcome) {
+      // The outcome line that corrects the attempt line. Nothing drains this
+      // directory — the spool is a local paper trail, not a queue — so the next
+      // occurrence of this failure dispatches again rather than being
+      // suppressed, which is also why the marker below is not written here.
+      const filePath = spoolReport({ envelope, reportId, appUrl, io: delivery });
+      delivery.log(`The report could not be sent. It is saved at ${filePath}`);
+      return;
+    }
+
+    // A successful send prints nothing further, and is the only thing that
+    // suppresses a repeat. Marker failures are swallowed on purpose.
+    try {
+      writeMarker(markerPath, entries, reportId, delivery.now);
+    } catch {
+      // Costs one duplicate report. Refusing to report would cost the report.
+    }
+  } catch {
+    // KTD10. The command that called this is already failing; the reporting
+    // path must not add a second failure mode, and there is nobody here to
+    // tell. Deliberately empty: a warning printed from this catch would be the
+    // second error message R10 promises the user will not see.
+  }
+}