@agentstrack/collector 0.2.1 → 0.4.1

package/CHANGELOG.md

@@ -10,6 +10,204 @@ released as a major version, with a migration note in this file.
 
 ## [Unreleased]
 
+## [0.4.1] — 2026-09-05
+
+### Fixed
+
+- **A session title could ship a piece of a secret (security).** `derived_title` is the first
+  meaningful line of your prompt, cut to 120 characters. Until now that cut was made on the **raw**
+  prompt and the secret scan ran afterwards, on the already-shortened title. If a key happened to
+  straddle the 120-character boundary, the cut split it in two, the leftover head no longer looked
+  like a key to any pattern, and it was uploaded as ordinary title text. A prompt of a hundred
+  characters followed by an `sk-ant-…` key produced a title ending in `sk-ant-api03-AAAAA…` while
+  the event dutifully reported `secrets_redacted: [{ anthropic_key, 1 }]` — the tally was right and
+  the title still carried a fragment.
+
+  The prompt is now redacted **before** the title is taken from it, in all three adapters (Claude
+  Code, Codex, OpenCode), so a truncation can only ever cut through a `[REDACTED:…]` marker. The
+  privacy pipeline still redacts `derived_title` afterwards; that pass is now a no-op and stays in
+  place as defence in depth.
+
+  The same cut-then-scan mistake applied to a Codex `error` event's `message`, truncated to 1000
+  characters; it is redacted before truncation now too.
+
+  **What to do:** only a partial value could escape, never a whole one, and only when a secret sat
+  across the cut. But a fragment is enough to identify which key was pasted, and the rest of it may
+  be guessable from context. If you have used `analytics` or `full` mode, look through your existing
+  session titles for key-shaped fragments, and rotate anything you find. Titles produced from 0.4.1
+  on are safe.
+
+  Fragments already uploaded stay in the product until you delete those sessions — upgrading the
+  collector does not rewrite history.
+
+### Changed
+
+- Documented the ordering (redact, then truncate) in the README and `docs/EVENT_SCHEMA.md`, and
+  corrected two stale lines there that still said `privacy.prompts: never` leaves `derived_title`
+  in place under `mode: full`. It has not since 0.4.0 — `never` drops it in every mode.
+
+## [0.4.0] — 2026-09-05
+
+### Added
+- **Secret exposure is reported as metadata.** When local redaction fires, the event now carries
+  `secrets_redacted: [{ kind, count }]` — which pattern matched and how many times, sorted by kind
+  and omitted entirely when nothing fired. The matched value never travels: not the text, not a
+  prefix of it, not a hash, not the surrounding context. The tally is computed **before** the mode
+  strip, so it survives `metadata` mode — the mode where a team most wants to know a credential was
+  typed into an agent and least wants the credential itself. An org-supplied rule reports as the
+  single generic kind `org_rule`, because a rule name can itself describe the shape of that
+  organization's secrets.
+
+## [0.3.0] — 2026-09-05
+
+### Added
+- **Skills, sub-agents and workflows are named.** A Claude Code `tool_use` named `Skill` carries
+  `skill`; `Agent` carries `subagent_type` and `description`; `Workflow` carries `workflow_name`
+  (the `name` from the script's `meta` header, when it is that simple). The `Agent` call's prompt and the
+  script body are never copied out of the call; a sub-agent transcript's own opening prompt is a
+  prompt like any other and follows `privacy.prompts`. The extras ride on `tool.started` and on the matching
+  `tool.completed` / `tool.failed`.
+- **Sub-agent transcripts are attributed.** Claude Code writes each sub-agent to
+  `<session-uuid>/subagents/[workflows/<wf>/]agent-<id>.jsonl` with the parent's session id; the
+  tailer already walked them, but nothing said which lines were the sub-agent's. Every event from
+  such a file (or any line with `isSidechain: true`) now carries `sidechain: true`, `agent_id`,
+  `agent_kind` (`subagent` | `workflow`) and, from the sibling `agent-<id>.meta.json`, `agent_type`
+  — so the sub-agent's own `model.response` usage can be attributed to it server-side.
+- **`user.prompted.ultracode`**, `true` when the prompt contains the whole word `ultracode`
+  (case-insensitive). Computed locally before redaction, so it survives `metadata` mode; the prompt
+  does not travel to be inspected.
+- **Machine info on register and health.** Alongside `hostname`, `os` and `arch` the collector now
+  sends `os_release` and `machine_kind` — `ci` (a CI env var), `container`
+  (`/.dockerenv` or a docker/containerd/kubepods cgroup), `workstation` (macOS, Windows, or Linux
+  with a display), `server` (headless Linux), else `unknown`. Health repeats it, so a device that
+  changes shape is updated. See the README privacy section for what the server does with it.
+
+### Changed
+- `description` (the Agent tool's one-line label) is treated like a title: secret-redacted, and
+  dropped in `metadata` mode.
+
+### Security
+- **`api_url` must be `https`.** The bearer API key rides on every request, so `http` is now rejected
+  for any host except `localhost`/`127.0.0.1`/`[::1]`. `login` prints the URL it is about to use.
+- **The API key can stay off the command line.** `agentstrack login` now takes the key as an optional
+  argument and otherwise reads `AGENTSTRACK_API_KEY`, an echo-off terminal prompt, or stdin
+  (`agentstrack login < key.txt`), keeping it out of shell history and `ps`.
+- **`config.yaml` is written atomically at mode 600** — a temp file created 0600 then renamed over the
+  target, so a crash can no longer leave a truncated config or a brief world-readable window.
+- **Org redaction rules are bounded.** A server-supplied pattern that is malformed, over 256
+  characters, or using a backreference is skipped (as a malformed rule already was), the common
+  catastrophic nested-quantifier shapes (`(a+)+`, `(a|aa)+`, `((a+)b)+`) are rejected, and org rules
+  match only the first 64 KB of a value — a pathological pattern is much less likely to hang the
+  single-threaded daemon.
+
+### Fixed
+- **Claude Code tokens and cost were inflated ~1.8x.** Claude Code writes one `assistant` line per
+  content block of a single response, each repeating the same `message.id` and usage; every line
+  became a `model.response`. Usage is now emitted once per `message.id`.
+- **Claude Code tool outcomes were all named `unknown`.** `tool_result` blocks carry only a
+  `tool_use_id`; the name is now resolved from the `tool_use` that started the call.
+- **Claude Code prompts pasted with an image (or as text blocks) were never counted**, and slash
+  command echoes (`<command-name>`, `<command-message>`, `<local-command-stdout>`,
+  `<task-notification>`) were counted as human prompts. Both fixed.
+- **Codex sessions went dark after a collector restart.** The session id lived only in memory from
+  `session_meta`; it is now seeded from the rollout file name, which carries the same uuid.
+- **Codex cached tokens were billed twice.** `cached_input_tokens` is a subset of `input_tokens`
+  in Codex; the collector now subtracts it so the two are exclusive, as the schema documents.
+- **Codex shell commands landed as `shell` with `duration_ms: 0` and never failed.**
+  `exec_command_end` carries an argv list, a `{secs,nanos}` duration and a numeric exit code;
+  `function_call_output.output` is a string. Both are read as they really are, and `tool.failed`
+  is emitted on a non-zero exit.
+- **OpenCode `session.ended` was rejected by the server on every emit** (missing
+  `external_session_id`, `reason` outside the enum). It now sends `reason: normal` with the
+  archived/compacted distinction in `end_kind`.
+- **OpenCode resumed sessions never got a `session.started`.** Sessions are fetched by
+  `time_updated` but starts were gated on a `time_created` cursor; a per-session marker in the
+  spool's meta store replaces it.
+- **`logout` now tears the service down first.** It previously left the launchd/systemd unit
+  installed, so the supervisor kept restarting an unauthenticated collector. Both units now restart
+  only on a crash (launchd `KeepAlive`/`SuccessfulExit`, systemd `Restart=on-failure` with a
+  5-in-5-minutes start limit), and the unauthenticated foreground path exits cleanly so the
+  supervisor idles.
+- **Service units handle paths with spaces and non-ASCII characters.** The CLI path is resolved with
+  `fileURLToPath` instead of a percent-encoded `URL.pathname`, plist strings are XML-escaped, and
+  systemd `ExecStart` arguments are quoted. `AGENTSTRACK_HOME` is written into the unit when set.
+- **A second foreground `start` refuses to run** when one is already collecting (checked via the pid
+  file, created with `wx`), preventing two collectors from racing on one spool.
+- **`stop` verifies the pid still belongs to a collector** (via `ps`) before signalling it, so a
+  recycled pid in a stale pid file is not killed.
+- **`doctor` reports the real scan window.** It now prints `modified in the last N day(s)` using
+  `tracking.max_age_days` instead of a hard-coded "7 days".
+- **`git.commit` polling stops re-diffing history every tick.** Each repo's `git log --since` now
+  starts from its last poll, SHAs are listed before any diffstat so `git show --numstat` runs only for
+  commits not yet emitted, and the emitted-SHA guard is pruned by age instead of cleared wholesale, so
+  a commit inside the lookback window is never re-emitted.
+
+### Changed
+- `detect()` reads only the first 16 KB of the newest transcript (by mtime) for the agent version,
+  cached on mtime, instead of the whole file every 5 s. OpenCode keeps one read-only database
+  handle with prepared statements rather than opening and closing one per query, and caches the
+  version for 60 s.
+- The contract test now runs every adapter fixture through the server's own payload schemas when
+  the server checkout is present, and fails (rather than skips) when `AGENTSTRACK_SERVER_REPO` is
+  set but missing.
+- **Node floor is `>=22`** (was `>=24`), matching `.nvmrc` and the runtime the code actually needs;
+  CI now tests Node 22 and 24.
+- `status` shows an upload-paused reason when one is present.
+
+### Fixed — daemon, queue and transport
+- **The upload failure policy ran once per concurrent batch, not once per wave.** With
+  `upload.concurrency: 4` a dead API escalated the backoff counter by four per wave (5-minute waits
+  after two waves), slept inside the wave so tailing froze for the duration, and a sibling's success
+  reset the counter or undid a `413` halving. `sendBatch` now returns a pure outcome and `flush()`
+  applies the policy once on the wave: halve once, one backoff step, strikes only for poison
+  batches, counter reset only when the whole wave succeeded. Backoff sets a next-upload time instead
+  of sleeping, honours `Retry-After` / `Retry-After-ingest` as the minimum, and a daemon tick sends
+  at most five waves before scanning again. Covered by `src/queue/flush.test.ts`.
+- **`401`/`403` no longer count strikes against telemetry.** They pause uploads (`status` shows the
+  reason), as does an over-quota `200` — previously acked and dropped locally with the `quota` block
+  ignored — and a `200` that rejects every event as malformed, which now logs a version-mismatch
+  error instead of deleting the batch.
+- **Checkpoints were written before the events were spooled.** A throw between the two lost those
+  lines for good. The tailer now streams in 4 MB chunks and commits each chunk's checkpoint in the
+  same transaction as its events; a line over 8 MB is skipped to the next newline and counted, at
+  most 64 MB per file is read per scan, short reads are looped, and one unreadable file no longer
+  aborts the scan for every file after it.
+- **Re-reading a transcript double-counted on the server.** `event_id` was a fresh `randomUUID` per
+  spool write; it is now derived from the adapter, file, byte offset and line content (a UUID v8
+  shape), so a rotated inode, a purged spool or a second collector on the same files dedupes.
+- **`VERSION` was hard-coded `0.1.0`.** It is read from `package.json`; the CLI, register and health
+  report the published version, and every request carries `User-Agent: agentstrack-collector/<v>`.
+- **A Claude Code response spanning a restart was billed twice.** `model.response` is now keyed on
+  `message.id` (the daemon's deterministic id, seeded by the adapter), not on the line, so the
+  server's dedupe absorbs the second line's copy after a restart.
+- **One rejected event paused every upload as a "schema mismatch".** A single-event batch the
+  server rejects is now struck like any other poison event; the pause is reserved for a whole
+  batch rejected without a quota reason.
+- **A failed commit left the checkpoint cache ahead of disk.** `setCheckpoint()` updated the
+  in-memory Map before COMMIT; the cache is now reloaded from the table when a transaction throws.
+- **OpenCode cursors and started-markers were written before the events they covered.** They are
+  now buffered and committed in the same transaction as the enqueue, so a full disk cannot mark a
+  session started that was never spooled.
+- **systemd `WorkingDirectory=` was quoted.** Path-typed settings are not unquoted by systemd; the
+  unit now writes the bare path (`ExecStart=` keeps its quoting).
+- **Claude Code and Codex sessions never ended.** The daemon emits `session.ended`
+  (`reason: timeout`) for a session quiet longer than `tracking.idle_timeout_seconds`, stamped at
+  the moment the timeout elapsed, and `reason: unknown` for anything still open on shutdown.
+- The batch response is validated with zod at the trust boundary; an unreadable body is retried,
+  never acked. Rejected `allSettled` outcomes are logged instead of swallowed. Local `batch_size` is
+  clamped to the server's `max_batch_events`.
+
+### Changed — daemon, queue and transport
+- The spool is `VACUUM`ed at open when the freelist is both over 2048 pages and more than half the
+  file (a 206 MB spool holding 78 events was observed), the WAL is capped at 8 MB
+  (`journal_size_limit`), statements are prepared once, checkpoints are cached in memory so an
+  unchanged file costs no SQL, and WAL/SHM are chmod 600 after they exist.
+- `describeRepo` is cached per scan pass; `flush()`, `reportHealth()` and `depth()` are inside the
+  loop's try/catch; the log rotates once at 5 MB to `collector.log.1` and a scan pass writes one
+  `Queued N events across M files` line instead of one per file.
+- Org redaction rules are compiled once per server-config refresh and handed to the privacy
+  pipeline pre-compiled, instead of being recompiled for every event.
+
 ## [0.2.1] — 2026-08-31
 
 ### Fixed
@@ -203,5 +401,15 @@ As released. Several of these have since been fixed — see `## Unreleased` abov
 - The service installer supports launchd and systemd only. `agentstrack start --foreground` works
   anywhere Node 20+ does.
 
-[Unreleased]: https://github.com/agentstrack/collector/compare/v0.1.0...HEAD
+<!-- 0.2.0 and 0.4.0 have no tag: this repository's history was squashed before
+     it was made public, and no commit in it carries either version. The releases
+     were real (0.2.0 is on npm) and their notes stay above; the compare links
+     simply skip to the neighbouring tag that does exist. -->
+
+[Unreleased]: https://github.com/agentstrack/collector/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/agentstrack/collector/compare/v0.3.0...v0.4.1
+[0.4.0]: https://github.com/agentstrack/collector/compare/v0.3.0...v0.4.1
+[0.3.0]: https://github.com/agentstrack/collector/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/agentstrack/collector/compare/v0.1.0...v0.2.1
+[0.2.0]: https://github.com/agentstrack/collector/compare/v0.1.0...v0.2.1
 [0.1.0]: https://github.com/agentstrack/collector/releases/tag/v0.1.0

package/README.md

@@ -5,7 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/@agentstrack/collector.svg)](https://www.npmjs.com/package/@agentstrack/collector)
 [![CI](https://github.com/agentstrack/collector/actions/workflows/ci.yml/badge.svg)](https://github.com/agentstrack/collector/actions/workflows/ci.yml)
 [![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
-[![Node](https://img.shields.io/badge/node-%3E%3D24-brightgreen.svg)](https://nodejs.org)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org)
 
 `@agentstrack/collector` turns the records Claude Code, Codex and OpenCode already keep on your
 machine into a normalized event stream:
@@ -30,7 +30,7 @@ before anything is: [Verify it yourself](#verify-it-yourself).
 ## Quick start
 
 ```bash
-npm install -g @agentstrack/collector       # requires Node >= 24
+npm install -g @agentstrack/collector       # requires Node >= 22
 
 agentstrack login at_live_xxxxxxxx_xxxxxxxx  # key from Settings → API keys
 agentstrack start                            # installs a login service and starts collecting
@@ -86,8 +86,10 @@ Nothing showing up? Run `agentstrack doctor`.
 | File paths, **relative to the project root by default** | Send absolute paths — which leak your username and your clients' names — unless you opt in |
 | Lines added/removed per edit, computed locally from the tool input | Send the lines themselves |
 | Git branch, commit SHA, additions/deletions/files changed | Send your git remote URL (only a SHA-256 of it) or commit messages and diffs |
-| Locally generated session titles (`analytics` mode and above) | Send the prompt those titles were derived from |
-| Your hostname, OS, arch and each detected agent's version — **once, at registration** | Store the raw hostname server-side (it is kept only as a SHA-256) |
+| A session title — the first line of the prompt, secret-redacted and then capped at 120 chars (`analytics` mode and above) | Send the rest of the prompt those titles were taken from |
+| Your hostname, OS and release, arch, Node version, a coarse machine kind (`workstation` / `server` / `container` / `ci`) and each detected agent's version — at registration and with each health report | Show your hostname or IP address in the product — see [Machine info](#machine-info) |
+| That local redaction fired: which pattern matched and how many times (`secrets_redacted`), in every privacy mode | Send the secret it matched — not the text, not a prefix of it, not a hash of it, not the characters around it |
+| Which skill, sub-agent type or workflow a Claude Code session invoked, and which events came from a sub-agent | Copy the `Agent` call's prompt or a workflow script's body out of the call (a sub-agent transcript's own opening prompt follows `privacy.prompts` like any other prompt) |
 | | Install hooks or modify `~/.claude/settings.json` / `~/.codex/hooks.json` |
 | | Send `organization_id` or `user_id` — they are not in the wire format at all |
 | | Watch your keyboard, your screen, or any process on your machine |
@@ -177,7 +179,7 @@ agentstrack doctor --json               # structured diagnostics, safe to paste
                                    ▼
        ┌────────────────────────┐
        │    privacy pipeline    │  mode-based content strip
-       │                        │  → 15 built-in secret rules + org rules
+       │                        │  → 16 built-in secret rules + org rules
        │                        │  → path normalization
        │                        │  → raw content DISCARDED HERE
        └───────────┬────────────┘
@@ -198,8 +200,20 @@ collector keeps parsing and keeps spooling; when the network returns it drains o
 over 1 KB are gzipped.
 
 **Restart is safe.** File read offsets live in the same SQLite database as the queue, keyed by
-`(path, inode)`. A restart resumes mid-file. If a file is replaced (new inode) or truncated (offset
-past the end), it is re-read from the start rather than silently skipped.
+`(path, inode)`, and a chunk's offset is committed in the **same transaction** as the events parsed
+from it — a crash or a full disk between "read" and "queued" re-reads those lines rather than losing
+them. A restart resumes mid-file. If a file is replaced (new inode) or truncated (offset past the
+end), it is re-read from the start rather than silently skipped. Re-reading never double-counts:
+every event's `event_id` is derived from the file, the line's byte offset and the line's content, so
+the server's dedupe absorbs a replay. A Claude Code `model.response` is keyed on its `message.id`
+instead, since one response spans several lines; an idle `session.ended` on the agent, session and
+last-activity time. Only events with no source line (`git.commit`, database-backed agents) get a
+random id.
+
+**Big files are streamed, not slurped.** Transcripts are read in 4 MB chunks with the partial line
+carried across the boundary, at most 64 MB per file per scan so a first import keeps yielding to the
+upload loop. A single line over 8 MB is skipped to the next newline and counted in the log — never
+buffered, never logged. One unreadable file is logged and skipped; it cannot stall the other files.
 
 **A line the agent is still writing is never consumed.** The tailer advances its checkpoint only as
 far as the **last complete newline**; a partial trailing line is left unread and picked up whole on
@@ -209,9 +223,18 @@ so both halves would fail to parse and that event would be lost. Byte offsets ar
 raw buffer, not from decoded text, so a multi-byte character cannot desynchronise the position
 either.
 
-**Backpressure is handled.** A `413` halves the batch size and the collector recovers it on the next
-success. A `5xx`, a timeout, a `408` or a `429` is retried with jittered exponential backoff (1s
-base, capped at 5 minutes). A `4xx` that is none of those means the server will never accept the
+**Backpressure is handled, once per wave.** Batches go out `upload.concurrency` at a time, and the
+failure policy runs on the wave's collected outcomes rather than inside each request — so four
+failing siblings cost one backoff step, not four, and a sibling's success cannot undo a `413`
+shrink. A `413` halves the batch size once (never above the server's `max_batch_events`) and it
+creeps back up on success. A `5xx`, a timeout, a `408` or a `429` sets the next upload time with
+jittered exponential backoff (1s base, capped at 5 minutes, or the server's `Retry-After` if longer)
+— the daemon never sleeps on it, so tailing continues meanwhile. A daemon tick sends at most five
+waves before scanning again. Three responses **pause** uploads instead: a `401`/`403` (the key, not
+the events, is the problem), a `200` whose `quota.exceeded` says the org is over its monthly cap,
+and a `200` that rejects every event as malformed (the collector is probably older than the server).
+Nothing is acked or dropped while paused; `agentstrack status` shows the reason, and the pause lifts
+by itself once a wave succeeds. A `4xx` that is none of those means the server will never accept the
 batch: **the attempt counter is incremented for the events in that batch only, and one of them is
 deleted once it reaches `upload.max_retries` (default 8)**. It is not parked and it does not come
 back — a poison event must not be able to block the queue forever.
@@ -243,6 +266,9 @@ Two properties of that deletion are worth stating explicitly, because both are e
 
 `analytics` is the honest middle: the title is computed **on your machine** from the prompt, and then
 the prompt is deleted. The server receives `"fix flaky auth test"`, never the 900 words you typed.
+The prompt is redacted **before** the title is cut out of it, so the cut can only ever land inside a
+`[REDACTED:…]` marker and never through the middle of a key. Before 0.4.1 it was cut first, which
+could ship half of a secret — see the CHANGELOG.
 
 If even the title is too much, `privacy.prompts: never` drops that too: in `analytics` it strips
 `derived_title`, so nothing derived from a prompt leaves the machine, without giving up token, tool
@@ -266,8 +292,8 @@ daemon cannot drift.
 
 ### Built-in secret redaction
 
-Every free-text field that survives the mode strip (`prompt_text`, `derived_title`, `message`,
-`command`) passes through these 15 rules, most-specific first, on your machine:
+Every free-text field (`prompt_text`, `derived_title`, `message`, `command`, `description`) passes
+through these 16 rules, most-specific first, on your machine:
 
 | Rule | Catches |
 |---|---|
@@ -284,19 +310,43 @@ Every free-text field that survives the mode strip (`prompt_text`, `derived_titl
 | `jwt` | three-segment `eyJ…` tokens |
 | `bearer_header` | `Bearer <token>` → `Bearer [REDACTED]` |
 | `basic_auth_url` | `https://user:pw@host` → `https://[REDACTED]@host` |
+| `inline_password_flag` | `-pSECRET`, `--password=SECRET`, `--password "SECRET"` |
 | `env_assignment` | `*SECRET*=`, `*TOKEN*=`, `*PASSWORD*=`, `*PASSWD*=`, `*APIKEY*=`, `*API_KEY*=`, `*ACCESS_KEY*=`, `*PRIVATE_KEY*=` |
 | `generic_hex_secret` | bare hex strings of 40+ characters |
 
-A match is replaced in place, and most rules substitute `[REDACTED:rule_name]`. Four do not:
+A match is replaced in place, and most rules substitute `[REDACTED:rule_name]`. Five do not:
 `bearer_header` → `Bearer [REDACTED]` and `basic_auth_url` → `scheme://[REDACTED]@host` keep the
-surrounding syntax so the shape of the command survives, `env_assignment` → `NAME=[REDACTED]` keeps
-the variable name, and `generic_hex_secret` substitutes the shorter `[REDACTED:hex]`. Your
-organization can add patterns server-side; a malformed org pattern is skipped rather than breaking
-the collector.
+surrounding syntax so the shape of the command survives, `env_assignment` → `NAME=[REDACTED]` and
+`inline_password_flag` → `--password=[REDACTED]` keep the variable or flag name, and
+`generic_hex_secret` substitutes the shorter `[REDACTED:hex]`. Your
+organization can add patterns server-side; an org pattern that is malformed, longer than 256
+characters, or using a backreference is skipped, the common catastrophic nested-quantifier shapes
+(`(a+)+`, `(a|aa)+`, `((a+)b)+`) are rejected — a heuristic, not a proof — and org patterns are
+matched against at most the first 64 KB of any value.
 
 Redaction is defence in depth, not the primary control. The primary control is that in `metadata`
 and `analytics` modes the content is **deleted locally** and never enters the pipeline at all.
 
+### What a redaction reports
+
+When a rule fires, the event carries `secrets_redacted` — a list of `{ kind, count }`, sorted by
+kind, absent when nothing fired:
+
+```json
+"secrets_redacted": [{ "kind": "aws_access_key", "count": 1 }]
+```
+
+Plainly: **we report that a secret-shaped string was found and which pattern matched it. We never
+send the value.** Not the matched text, not a prefix of it, not a hash of it, not the surrounding
+context — there is nothing in the payload to reverse. A rule your organization added reports as the
+single generic kind `org_rule`, because a rule name (`acme_prod_db_password`) can itself describe
+the shape of your secrets.
+
+This travels in **every** mode, `metadata` included: the tally is computed before the mode strip
+deletes the text it was computed from. A count is metadata; the prompt it came from is not. And
+`metadata` is exactly the mode where a team most wants to know that a live credential was pasted
+into an agent — the point being to go rotate it, which needs no copy of it.
+
 ### How file paths are handled
 
 With `file_paths: relative` (the default):
@@ -311,6 +361,22 @@ The project root itself (`repo.project_path`) is **dropped entirely** in `never`
 modes — it is only transmitted if you opt into `file_paths: absolute`. Repositories are correlated
 by `remote_hash`, a SHA-256 of the normalized remote URL, not by path.
 
+### Machine info
+
+`login` (registration) and the daemon's health report, once a minute, send: `hostname`, `os`
+(`darwin` / `linux` / `win32`), `os_release` (`os.release()`), `arch`, and
+`machine_kind` — `ci` when `CI`, `GITHUB_ACTIONS` or `GITLAB_CI` is set; `container` when
+`/.dockerenv` exists or `/proc/1/cgroup` mentions docker, containerd or kubepods; `workstation` on
+macOS and Windows, or Linux with `DISPLAY` / `WAYLAND_DISPLAY` / a graphical `XDG_SESSION_TYPE`;
+`server` for headless Linux; `unknown` otherwise. It is derived from those probes only.
+
+The server keeps the hostname (raw, plus a SHA-256 that keys registration) and the IP address it
+saw the register, health and upload requests come from, **for operations and abuse prevention
+only** — telling one machine's collector from another, and shutting off a key that is being abused.
+Neither is returned by any user-facing endpoint or shown anywhere in the product; the dashboard
+identifies a device by its label and machine kind. Everything else in the list (OS, arch, kind,
+versions) is what the device page shows.
+
 ### Excluding a project entirely
 
 ```yaml
@@ -345,14 +411,18 @@ events at all** — not even counts. Edit the YAML and restart the collector.
 agentstrack login <api-key> [--api-url <url>] [--label <name>]
 ```
 
-The key is a **positional argument** — there is no interactive prompt and no environment variable.
-`--api-url` points at a self-hosted instance; `--label` names this machine in the dashboard.
+The key argument is **optional**. Passing it on the command line leaves it in your shell history and
+in `ps`, so `login` also reads `AGENTSTRACK_API_KEY`, or prompts on the terminal (echo off), or takes
+the key on stdin — `agentstrack login < key.txt`. `--api-url` points at a self-hosted instance and
+**must be `https`** (plain `http` is accepted only for `localhost`); `login` prints the URL it is
+about to use. `--label` names this machine in the dashboard.
 Registration is idempotent on (user, hostname hash), so re-running `login` on the same machine reuses
 the existing collector instead of fragmenting its history. The config file is written mode `600`, in
 a directory created mode `700`.
 
-The registration payload is `hostname`, `label`, `os`, `arch`, the collector's own version, and one
-entry per configured agent: `{ agent, version }`. The **agent version is the real one**, read out of
+The registration payload is `hostname`, `label`, `os`, `os_release`, `arch`, `machine_kind`,
+(see [Machine info](#machine-info)), the collector's own version, and one entry per
+configured agent: `{ agent, version }`. The **agent version is the real one**, read out of
 a transcript the agent already wrote (`2.1.247`, say, from Claude Code's `version` field). Where an
 adapter cannot cheaply establish a version at detection time the field is simply **omitted** rather
 than filled with a placeholder, so a missing version in the dashboard means "not reported", never
@@ -372,8 +442,11 @@ If your local privacy mode is stricter than the org's, login says so and keeps y
 
 `agentstrack start` writes a **launchd** agent on macOS (`~/Library/LaunchAgents/ai.agentstrack.collector.plist`)
 or a **systemd user unit** on Linux (`~/.config/systemd/user/agentstrack.service`), loads it, and
-returns. Neither needs root. `-f` / `--foreground` runs in the terminal instead — best for a first
-run, and the only mode where `status` reports `Running: yes`.
+returns. Neither needs root. The unit restarts the collector only on a **crash**, not after a clean
+exit — after `logout` the collector exits cleanly and the supervisor leaves it stopped instead of
+respawning it every few seconds (launchd `KeepAlive`/`SuccessfulExit`, systemd `Restart=on-failure`
+with a 5-in-5-minutes start limit). `-f` / `--foreground` runs in the terminal instead — best for a
+first run, and the only mode where `status` reports `Running: yes`.
 
 `agentstrack stop` removes the service unit *and* signals a foreground collector. There is no
 "stop but keep the unit"; use `agentstrack service install` to put it back.
@@ -389,9 +462,9 @@ Configuration
 
 Agents
   ✓ claude_code transcripts found
-    225 file(s) modified in the last 7 days
+    225 file(s) modified in the last 7 days   # window is tracking.max_age_days (default 7)
   ✓ codex transcripts found
-    3 file(s) modified in the last 7 days
+    3 file(s) modified in the last 7 days     # window is tracking.max_age_days (default 7)
 
 Connectivity
   ✗ API reachable at https://api.agentstrack.ai
@@ -507,10 +580,10 @@ privacy:
 
   # never | local_summary_only (default) | full
   # `full` is what keeps `mode: full` from uploading prompt text unless you also
-  # ask for it here. `never` suppresses prompt text in every mode, and in
-  # `analytics` it additionally drops the locally derived `derived_title`, so
-  # nothing derived from a prompt leaves the machine at all. Under `mode: full`
-  # it does NOT drop `derived_title` — see the privacy section.
+  # ask for it here. `never` suppresses prompt text in every mode, and it
+  # additionally drops the locally derived `derived_title` in every mode too —
+  # `analytics` and `full` alike — so nothing derived from a prompt leaves the
+  # machine at all. See the privacy section.
   prompts: local_summary_only
 
   # never (default) | full
@@ -569,7 +642,7 @@ database filename or an absolute path — the same override OpenCode itself hono
 
 | Agent | Status | Reads |
 |---|---|---|
-| **Claude Code** | ✅ Stable | `~/.claude/projects/<slug>/<session-uuid>.jsonl` |
+| **Claude Code** | ✅ Stable | `~/.claude/projects/<slug>/<session-uuid>.jsonl`, plus `<session-uuid>/subagents/**/agent-<id>.jsonl` |
 | **Codex** | ✅ Stable | `~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl` |
 | **OpenCode** | ✅ Stable | `~/.local/share/opencode/opencode.db` — SQLite, opened **read-only** |
 | Gemini CLI · Cursor · Cline · Copilot CLI | 🗓 Planned | ids reserved in the schema, no adapter yet |
@@ -593,6 +666,7 @@ identical things:
 | Commits | ✅ (from `git log`, not the transcript) | ✅ (same) | ✅ (same) |
 | Plan / subscription type | ➖ | ✅ `plan_type` | ➖ |
 | Account attribution | ✅ from `~/.claude.json` | ➖ no account file | ✅ from `account.json`, per provider |
+| Skills / sub-agents / workflows | ✅ `Skill`, `Agent`, `Workflow` tool calls named; sub-agent transcripts stamped `sidechain` | ➖ Codex's `spawn_agent` collaboration tools are defined in its prompt but no rollout on hand shows one invoked, so nothing is parsed yet | ➖ `parent_session_id` only |
 
 Every adapter is read-only. Adapter formats drift between agent releases: an unparseable line is
 skipped, never fatal to the file.
@@ -678,8 +752,10 @@ gzipped (`content-encoding: gzip`).
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| `401` in the log | Key revoked or wrong | `agentstrack login <new-key>` |
-| `403` | Key lacks ingest permission | Issue a new key |
+| `Uploads paused (auth)` — `401` | Key revoked or wrong | `agentstrack login <new-key>`; nothing was dropped |
+| `Uploads paused (auth)` — `403` | Key lacks ingest permission | Issue a new key; nothing was dropped |
+| `Uploads paused (quota)` | Org over its monthly event cap | Events stay spooled and resume when the cap resets or the plan changes |
+| `Uploads paused (schema)` | Server rejects every event — collector older than the API | Upgrade the collector; nothing was dropped |
 | `fetch failed`, `ETIMEDOUT` | Network, VPN or proxy | Set `HTTPS_PROXY`; events keep spooling meanwhile |
 | `Server rejected the batch as too large` | Batch above the server's limit | Automatic — batch size halves and recovers |
 | `Batch permanently rejected: … (dropped N)` | Non-retryable `4xx` | N events **in that batch** hit `max_retries` and were deleted. Nothing outside the batch is touched. Check the API version matches the collector's schema. |
@@ -720,7 +796,8 @@ grep -i "error\|failed\|rejected" ~/.agentstrack/collector.log | tail -20
 ```
 
 The log records counts, queue depths and `event_id`s — never payloads, prompts, code or keys. That is
-what makes it safe to attach to an issue. Please attach `agentstrack doctor --json` too.
+what makes it safe to attach to an issue. It rotates once at 5 MB to `collector.log.1`; a scan pass
+writes one `Queued N events across M files` line, not one per file. Please attach `agentstrack doctor --json` too.
 
 ### Complete reset
 
@@ -739,15 +816,14 @@ Honest list of things that are **not** in 0.1.0, so you do not go looking for th
 [ROADMAP.md](./ROADMAP.md) has the same list with the design constraints and what "help wanted"
 means for each.
 
-- **Backfill window control** (`sync --since 30d`). Today the daemon reads whatever was modified in the last 7 days, and that window is not configurable.
+- **Backfill window control** (`sync --since 30d`). Today the window is `tracking.max_age_days` (default 7) for every run; there is no per-invocation override.
 - **`config get` / `config set` / `config edit`** — edit the YAML by hand for now.
 - **`--verbose` logging** and per-run agent selection (`start --agent codex`); use `tracking.agents`.
-- **Local time accounting.** Human-active / agent-active / idle windows are derived server-side from the event stream; `tracking.idle_timeout_seconds` is parsed by the collector but not used by it.
+- **Local time accounting.** Human-active / agent-active / idle windows are derived server-side from the event stream; the collector uses `tracking.idle_timeout_seconds` only to decide when a quiet session has ended.
 - **Process metrics.** `tracking.process_metrics` is accepted and ignored.
-- **`session.ended`, `heartbeat`, `model.request` and `git.branch_changed`** are in the schema but no adapter emits them yet.
+- **`heartbeat`, `model.request` and `git.branch_changed`** are in the schema but no adapter emits them yet. `session.ended` is not read from any Claude Code or Codex transcript either — the daemon emits it after `tracking.idle_timeout_seconds` of quiet (`reason: timeout`) or on shutdown (`reason: unknown`).
 - **Local task classification** (`task_category`) — the field exists in the schema; the collector only derives a title.
-- **Windows.** The service installer covers launchd and systemd only; `--foreground` works anywhere Node 24+ does.
-- **Content-derived `event_id`.** Ids are random per enqueue, so retrying a batch is safe but re-reading a truncated transcript would create duplicates.
+- **Windows.** The service installer covers launchd and systemd only; `--foreground` works anywhere Node 22+ does.
 - **`MultiEdit`.** The Claude Code adapter derives file changes from `Edit`, `Write`, `NotebookEdit` and `Read`; a `MultiEdit` call is still recorded as `tool.started`/`tool.completed`, but produces no `file.changed` events and no line counts.
 
 ---

package/dist/adapters/claude.d.ts

@@ -14,10 +14,22 @@ import { type TokenUsage } from '../schema.js';
  *             "output_tokens_details":{"thinking_tokens":257}}},"timestamp":"…"}
  *
  * Tool calls appear as tool_use / tool_result blocks inside message.content.
+ * One API response is written as SEVERAL assistant lines — one per content
+ * block (thinking, text, tool_use) — each repeating the same message.id and
+ * the same usage. Usage is therefore billed once per message.id, not per line.
+ *
+ * Sub-agents (the Agent tool, and Workflow scripts) write their own transcript
+ * under <session-uuid>/subagents/[workflows/<wf>/]agent-<id>.jsonl, with the
+ * parent's sessionId on every line, isSidechain: true and an agentId. A sibling
+ * agent-<id>.meta.json carries {"agentType","description","toolUseId",…}. Every
+ * event from such a line is stamped sidechain/agent_id/agent_kind/agent_type
+ * so the server can attribute the sub-agent's own usage to it.
  */
 export declare const CLAUDE_DIR: string;
 export declare class ClaudeCodeAdapter implements AgentAdapter {
     readonly id = "claude_code";
+    /** Cross-line facts within one transcript: a message's lines are contiguous. */
+    private readonly fileState;
     detect(): Promise<DetectionResult>;
     /**
      * The account Claude Code is signed in as right now.
@@ -34,6 +46,12 @@ export declare class ClaudeCodeAdapter implements AgentAdapter {
     private normalizeUser;
     private normalizeAssistant;
 }
+/**
+ * Maps Claude Code's usage block onto the normalized shape.
+ *
+ * thinking_tokens sits under output_tokens_details and is a SUBSET of
+ * output_tokens — it must not be added on top, or thinking gets billed twice.
+ */
 export declare function readUsage(raw: unknown): TokenUsage;
 /**
  * Line deltas for one edit, derived from the tool input.