@agentstrack/collector 0.2.1 → 0.3.0

package/dist/daemon.js

@@ -1,24 +1,34 @@
-import { randomUUID } from 'node:crypto';
-import { appendFileSync } from 'node:fs';
-import { hostname, arch, platform } from 'node:os';
-import { readdirSync, statSync, existsSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { appendFileSync, renameSync, statSync } from 'node:fs';
+import { readdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadConfig, saveConfig, SPOOL_PATH, LOG_PATH } from './config.js';
 import { Spool } from './queue/spool.js';
+import { machineInfo } from './machine.js';
 import { tailFile } from './queue/tailer.js';
-import { ApiClient, backoffMs } from './transport/client.js';
+import { deterministicEventId } from './queue/event-id.js';
+export { deterministicEventId };
+import { ApiClient, ApiError, backoffMs, VERSION } from './transport/client.js';
 import { ClaudeCodeAdapter } from './adapters/claude.js';
 import { CodexAdapter } from './adapters/codex.js';
 import { OpenCodeAdapter } from './adapters/opencode.js';
 import { applyPrivacy } from './privacy/pipeline.js';
+import { compileRules } from './privacy/redact.js';
 import { clampPrivacyMode } from './privacy/mode.js';
 import { isExcluded } from './privacy/paths.js';
 import { describeRepo } from './git/repo.js';
 import { GitCommitWatcher } from './git/commits.js';
 import { SCHEMA_VERSION } from './schema.js';
+export { VERSION };
+const LOG_MAX_BYTES = 5 * 1024 * 1024;
 export function log(message) {
     const line = `${new Date().toISOString()} ${message}\n`;
     try {
+        // One rotation, no compression: enough to keep a service's log bounded
+        // without making `tail -f` lose the current file.
+        if ((statSync(LOG_PATH, { throwIfNoEntry: false })?.size ?? 0) > LOG_MAX_BYTES) {
+            renameSync(LOG_PATH, `${LOG_PATH}.1`);
+        }
         appendFileSync(LOG_PATH, line);
     }
     catch {
@@ -91,6 +101,17 @@ export function listTranscripts(dir, maxAgeDays = 7) {
     walk(dir, 0);
     return found.sort((a, b) => b.mtime - a.mtime).map((f) => f.path);
 }
+/** Splits one peeked wave into `batchSize` slices, every event in exactly one. */
+export function chunkWave(wave, batchSize) {
+    const batches = [];
+    for (let i = 0; i < wave.length; i += batchSize)
+        batches.push(wave.slice(i, i + batchSize));
+    return batches;
+}
+/** Waves one daemon tick may send before scan() gets the loop back. */
+const MAX_WAVES_PER_TICK = 5;
+/** Spool meta key naming the current upload pause (`<reason>: <detail>`); `status` prints it. */
+export const UPLOAD_PAUSE_META = 'upload_paused_reason';
 export class Collector {
     config;
     spool;
@@ -99,6 +120,7 @@ export class Collector {
     /** Null when git metadata is switched off — then we never shell out to git. */
     commitWatcher;
     serverConfig = null;
+    orgRules = [];
     /**
      * When this collector started, and therefore the earliest event it can
      * honestly attribute to an account.
@@ -112,24 +134,34 @@ export class Collector {
      */
     liveSinceMs = Date.now();
     uploadFailures = 0;
-    /** Shrinks on 413, recovers on success. Never below 1. */
+    /** Shrinks on 413, recovers on success. Never below 1, never above maxBatchSize. */
     batchSize;
+    /** Local batch_size clamped to the server's max_batch_events. */
+    maxBatchSize;
+    /** Uploads are gated on this instead of sleeping, so scanning never stops. */
+    nextUploadAt = 0;
+    pausedReason = null;
+    /** cwd -> repo, valid for one scan pass. */
+    repoCache = new Map();
+    /** agent::session_id -> last activity, for idle session.ended. */
+    openSessions = new Map();
     running = false;
-    constructor(config) {
+    constructor(config, deps = {}) {
         this.config = config;
         if (!config.api_key)
             throw new Error('Not logged in. Run: agentstrack login <api-key>');
-        this.spool = new Spool(SPOOL_PATH);
-        this.client = new ApiClient({ apiUrl: config.api_url, apiKey: config.api_key });
+        this.spool = deps.spool ?? new Spool(SPOOL_PATH);
+        this.client = deps.client ?? new ApiClient({ apiUrl: config.api_url, apiKey: config.api_key });
         this.adapters = buildAdapters(config);
         this.commitWatcher = config.tracking.git_metadata ? new GitCommitWatcher() : null;
         this.batchSize = config.upload.batch_size;
+        this.maxBatchSize = config.upload.batch_size;
     }
     async start() {
         this.running = true;
         await this.ensureRegistered();
         await this.refreshServerConfig();
-        log(`Collector started — agents: ${this.adapters.map((a) => a.id).join(', ')}`);
+        log(`Collector ${VERSION} started — agents: ${this.adapters.map((a) => a.id).join(', ')}`);
         const scanInterval = 5_000;
         const uploadInterval = this.config.upload.interval_seconds * 1000;
         let lastUpload = 0;
@@ -142,19 +174,29 @@ export class Collector {
                 log(`Scan error: ${errorMessage(error)}`);
             }
             const now = Date.now();
-            if (now - lastUpload >= uploadInterval || this.spool.depth() >= this.batchSize) {
-                lastUpload = now;
-                await this.flush();
+            let more = false;
+            try {
+                if (now >= this.nextUploadAt && (now - lastUpload >= uploadInterval || this.spool.depth() >= this.batchSize)) {
+                    lastUpload = now;
+                    more = await this.flush(MAX_WAVES_PER_TICK);
+                }
+                if (now - lastHealth >= 60_000) {
+                    lastHealth = now;
+                    await this.reportHealth();
+                }
             }
-            if (now - lastHealth >= 60_000) {
-                lastHealth = now;
-                await this.reportHealth();
+            catch (error) {
+                log(`Upload error: ${errorMessage(error)}`);
             }
-            await sleep(scanInterval);
+            // A backlog alternates scan and flush without the 5s pause between them.
+            await sleep(more ? 0 : scanInterval);
         }
     }
     stop() {
         this.running = false;
+        // Whatever was open when we went down ended for a reason we cannot see.
+        if (this.config.collector_id)
+            this.endIdleSessions(0, 'unknown');
         this.spool.close();
     }
     /** Registers this device once and remembers the id. */
@@ -163,9 +205,7 @@ export class Collector {
             return;
         const agents = await Promise.all(this.adapters.map(async (a) => ({ agent: a.id, version: (await a.detect()).version })));
         const result = await this.client.registerCollector({
-            hostname: hostname(),
-            os: platform(),
-            arch: arch(),
+            ...machineInfo(),
             version: VERSION,
             // Report what this device enforces, so a session records the mode that
             // actually applied rather than the org default.
@@ -179,6 +219,8 @@ export class Collector {
     async refreshServerConfig() {
         try {
             this.serverConfig = await this.client.getConfig();
+            // Compiled once per config refresh, not once per event.
+            this.orgRules = compileRules(this.serverConfig.redaction_rules);
             // The org sets a ceiling; a stricter local mode is honoured, a looser one
             // is not. Same rule as `login`, shared so the two cannot drift.
             const effective = clampPrivacyMode(this.config.privacy.mode, this.serverConfig.privacy_mode);
@@ -186,6 +228,13 @@ export class Collector {
                 log(`Local privacy mode '${this.config.privacy.mode}' exceeds org policy '${this.serverConfig.privacy_mode}' — using org policy`);
                 this.config = { ...this.config, privacy: { ...this.config.privacy, mode: effective } };
             }
+            // The server's ceiling wins over the local batch_size; anything above it
+            // is a guaranteed 413 on every wave.
+            const serverMax = this.serverConfig.max_batch_events;
+            if (Number.isInteger(serverMax) && serverMax > 0) {
+                this.maxBatchSize = Math.min(this.config.upload.batch_size, serverMax);
+                this.batchSize = Math.min(this.batchSize, this.maxBatchSize);
+            }
         }
         catch (error) {
             log(`Could not fetch server config, using local defaults: ${errorMessage(error)}`);
@@ -196,6 +245,10 @@ export class Collector {
         const collectorId = this.config.collector_id;
         if (!collectorId)
             return;
+        this.repoCache.clear();
+        let queued = 0;
+        let files = 0;
+        let skipped = 0;
         for (const adapter of this.adapters) {
             const detection = await adapter.detect();
             if (!detection.installed)
@@ -205,34 +258,43 @@ export class Collector {
             const account = adapter.account?.();
             for (const watchPath of detection.watchPaths) {
                 for (const file of listTranscripts(watchPath, this.config.tracking.max_age_days)) {
-                    const { lines } = await tailFile(file, this.spool);
-                    if (lines.length === 0)
-                        continue;
-                    const normalized = [];
-                    for (const line of lines) {
-                        try {
-                            normalized.push(...adapter.normalize(line, { collectorId, sourceFile: file }));
-                        }
-                        catch (error) {
-                            // A parser bug on one line must not stop the whole file.
-                            log(`normalize error in ${file}: ${errorMessage(error)}`);
-                        }
+                    // One unreadable file must not stall every other file, every scan.
+                    try {
+                        const result = await tailFile(file, this.spool, (lines) => {
+                            const normalized = [];
+                            for (const { text, offset } of lines) {
+                                let events;
+                                try {
+                                    events = adapter.normalize(text, { collectorId, sourceFile: file });
+                                }
+                                catch (error) {
+                                    // A parser bug on one line must not stop the whole file.
+                                    log(`normalize error in ${file}: ${errorMessage(error)}`);
+                                    continue;
+                                }
+                                if (events.length === 0)
+                                    continue;
+                                // Same file, same byte, same text => same id, however often it is re-read.
+                                const line = createHash('sha256').update(`${adapter.id}\n${file}\n${offset}\n`).update(text).digest('hex');
+                                events.forEach((event, i) => normalized.push({ ...event, eventId: event.eventId ?? deterministicEventId(`${line}:${i}`) }));
+                            }
+                            this.commitWatcher?.observe(normalized);
+                            queued += this.enqueue(normalized, collectorId, account);
+                        });
+                        if (result.lines > 0)
+                            files += 1;
+                        skipped += result.skipped;
+                    }
+                    catch (error) {
+                        log(`tail error in ${file}: ${errorMessage(error)}`);
                     }
-                    this.commitWatcher?.observe(normalized);
-                    this.enqueue(normalized, collectorId, account);
                 }
             }
             // Database-backed agents have no lines to tail; they hand us events on
             // the same cycle, under the same gating and the same privacy pipeline.
             if (adapter.poll) {
                 try {
-                    const polled = await adapter.poll({
-                        collectorId,
-                        getMeta: (key) => this.spool.getMeta(key),
-                        setMeta: (key, value) => this.spool.setMeta(key, value),
-                    });
-                    this.commitWatcher?.observe(polled);
-                    this.enqueue(polled, collectorId, account);
+                    queued += await this.pollAdapter(adapter.poll.bind(adapter), collectorId, account);
                 }
                 catch (error) {
                     log(`poll error in ${adapter.id}: ${errorMessage(error)}`);
@@ -244,21 +306,82 @@ export class Collector {
         // actually touched, once per scan cycle.
         if (this.commitWatcher) {
             try {
-                this.enqueue(await this.commitWatcher.poll(), collectorId);
+                queued += this.enqueue(await this.commitWatcher.poll(), collectorId);
             }
             catch (error) {
                 log(`Commit scan error: ${errorMessage(error)}`);
             }
         }
+        queued += this.endIdleSessions(this.config.tracking.idle_timeout_seconds * 1000, 'timeout');
+        if (queued > 0)
+            log(`Queued ${queued} events across ${files} files`);
+        if (skipped > 0)
+            log(`Skipped ${skipped} oversized transcript lines`);
     }
-    enqueue(normalized, collectorId, adapterAccount) {
+    /**
+     * Polls a database-backed adapter. Its cursors and "already started" markers
+     * are buffered and written in the same transaction as the events — an
+     * enqueue that fails (SQLITE_FULL) must not leave a cursor pointing past
+     * rows that were never spooled, or a session marked started that never was.
+     */
+    async pollAdapter(poll, collectorId, account) {
+        const pending = new Map();
+        const polled = await poll({
+            collectorId,
+            getMeta: (key) => pending.get(key) ?? this.spool.getMeta(key),
+            setMeta: (key, value) => void pending.set(key, value),
+        });
+        this.commitWatcher?.observe(polled);
+        return this.spool.transaction(() => {
+            const queued = this.enqueue(polled, collectorId, account);
+            pending.forEach((value, key) => this.spool.setMeta(key, value));
+            return queued;
+        });
+    }
+    /**
+     * Emits session.ended for every tracked session quiet for longer than
+     * `idleMs`. Claude Code and Codex never write an end marker, so without this
+     * their sessions stay in_progress on the server forever. `occurred_at` is
+     * when the timeout elapsed, not now: a backfilled session ended back then.
+     */
+    endIdleSessions(idleMs, reason) {
+        const collectorId = this.config.collector_id;
+        if (!collectorId)
+            return 0;
+        const now = Date.now();
+        const ended = [];
+        for (const [key, s] of this.openSessions) {
+            if (now - s.lastAtMs < idleMs)
+                continue;
+            this.openSessions.delete(key);
+            const at = idleMs > 0 ? s.lastAtMs + idleMs : now;
+            ended.push({
+                event: {
+                    occurred_at: new Date(at).toISOString(),
+                    session_id: s.sessionId,
+                    agent: s.agent,
+                    agent_version: s.agentVersion,
+                    event_type: 'session.ended',
+                    payload: { external_session_id: s.sessionId, reason },
+                },
+                eventId: deterministicEventId(`session.ended\n${s.agent}\n${s.sessionId}\n${s.lastAtMs}`),
+            });
+        }
+        return this.enqueue(ended, collectorId);
+    }
+    repoFor(cwd) {
+        if (!this.repoCache.has(cwd))
+            this.repoCache.set(cwd, describeRepo(cwd));
+        return this.repoCache.get(cwd);
+    }
+    enqueue(items, collectorId, adapterAccount) {
         const envelopes = [];
-        for (const item of normalized) {
+        for (const item of items) {
             const cwd = item.cwd;
             // An excluded project never produces an event at all.
             if (cwd && isExcluded(cwd, this.config.privacy.excluded_projects))
                 continue;
-            const repo = cwd && this.config.tracking.git_metadata ? describeRepo(cwd) : item.repo;
+            const repo = cwd && this.config.tracking.git_metadata ? this.repoFor(cwd) : item.repo;
             const payload = repo
                 ? { ...item.event.payload, repo: { ...repo, ...(item.event.payload['repo'] ?? {}) } }
                 : { ...item.event.payload };
@@ -279,109 +402,208 @@ export class Collector {
             const envelope = {
                 ...item.event,
                 payload,
-                event_id: randomUUID(),
+                event_id: item.eventId ?? randomUUID(),
                 schema_version: SCHEMA_VERSION,
                 collector_id: collectorId,
             };
             const { event } = applyPrivacy(envelope, {
                 config: this.config,
                 projectRoot: repo?.project_path,
-                orgRules: this.serverConfig?.redaction_rules,
+                compiledRules: this.orgRules,
             });
             envelopes.push(event);
+            this.trackSession(event);
         }
-        const written = this.spool.enqueue(envelopes);
-        if (written > 0)
-            log(`Queued ${written} events (depth ${this.spool.depth()})`);
+        return this.spool.enqueue(envelopes);
+    }
+    trackSession(event) {
+        const key = `${event.agent}::${event.session_id}`;
+        if (event.event_type === 'session.ended') {
+            this.openSessions.delete(key);
+            return;
+        }
+        const at = Date.parse(event.occurred_at);
+        if (!Number.isFinite(at))
+            return;
+        const open = this.openSessions.get(key);
+        if (open) {
+            open.lastAtMs = Math.max(open.lastAtMs, at);
+            return;
+        }
+        this.openSessions.set(key, {
+            agent: event.agent,
+            agentVersion: event.agent_version,
+            sessionId: event.session_id,
+            lastAtMs: at,
+        });
     }
-    /** Drains the spool, oldest first, until it is empty or the server pushes back. */
     /**
-     * Drains the spool.
+     * Drains the spool, one wave of `upload.concurrency` batches at a time.
+     *
+     * Uploading is round-trip bound, not bandwidth bound — a first import moved
+     * ~330 events/s sequentially, which is one 100-event batch per ~300ms of
+     * mostly waiting — so sending several at once divides the wall clock of a
+     * backfill by roughly that number. Order is deliberately NOT preserved
+     * across in-flight batches: the server derives a session's start from
+     * min(recorded start, earliest stored event), so a later batch landing first
+     * is corrected once the rest arrive. Within a batch the spool still yields
+     * oldest-first.
      *
-     * Batches go out `upload.concurrency` at a time. Uploading is round-trip
-     * bound, not bandwidth bound — a first import moved ~330 events/s
-     * sequentially, which is one 100-event batch per ~300ms of mostly waiting —
-     * so sending several at once divides the wall clock of a backfill by roughly
-     * that number.
+     * The failure policy runs ONCE per wave, on the collected outcomes:
+     *  - any 413        -> batch size halves once
+     *  - any retryable  -> one backoff step; uploads are gated on nextUploadAt,
+     *                      never slept on, so tailing continues meanwhile
+     *  - any poison     -> strikes for those batches only
+     *  - 401/403, quota, whole-batch schema rejection -> paused, nothing dropped
+     *  - every batch ok -> counter reset, batch size creeps back up
      *
-     * Order is deliberately NOT preserved across in-flight batches, and does not
-     * need to be: the server derives a session's start from
-     * min(recorded start, earliest stored event) and re-runs reconstruction after
-     * every batch, so a later batch arriving first is corrected once the rest
-     * land. Within a single batch the spool still yields oldest-first.
+     * Returns true when it stopped only because `maxWaves` ran out, i.e. there
+     * is more to send right now.
      */
-    async flush() {
-        for (;;) {
-            const concurrency = Math.max(1, this.config.upload.concurrency);
+    async flush(maxWaves = Number.POSITIVE_INFINITY) {
+        const concurrency = Math.max(1, this.config.upload.concurrency);
+        for (let n = 0; n < maxWaves; n++) {
             // One peek for the whole wave. Peeking per batch would hand the same
-            // rows to every request, because nothing is acked until they return —
-            // the same events would be uploaded `concurrency` times.
+            // rows to every request, because nothing is acked until they return.
             const wave = this.spool.peek(this.batchSize * concurrency);
             if (wave.length === 0) {
                 this.uploadFailures = 0;
-                return;
-            }
-            const batches = [];
-            for (let i = 0; i < wave.length; i += this.batchSize) {
-                batches.push(wave.slice(i, i + this.batchSize));
+                this.resume();
+                return false;
             }
+            const batches = chunkWave(wave, this.batchSize);
             // allSettled, not all: one failing batch must not abandon its siblings,
             // whose events are already accepted by the server.
-            const outcomes = await Promise.allSettled(batches.map((b) => this.sendBatch(b)));
-            // A false outcome means the failure policy already ran — batch size
-            // halved, backoff slept, or a poison batch dropped — and the caller
-            // should re-enter on the next tick rather than keep draining this wave
-            // with settings that just changed.
-            if (outcomes.some((o) => o.status === 'rejected' || o.value === false))
-                return;
+            const settled = await Promise.allSettled(batches.map((b) => this.sendBatch(b)));
+            let allOk = true;
+            let tooLarge = false;
+            // `null as` keeps the declared union: a plain `= null` narrows to never below.
+            let retry = null;
+            let paused = null;
+            let accepted = 0;
+            let duplicates = 0;
+            const outcomes = settled.map((s) => s.status === 'fulfilled' ? s.value : { kind: 'retry', error: s.reason });
+            for (const [i, outcome] of outcomes.entries()) {
+                const ids = batches[i].map((b) => b.eventId);
+                if (outcome.kind === 'ok') {
+                    // Duplicates are acknowledged too — the server already has them.
+                    this.spool.ack(ids);
+                    accepted += outcome.result.accepted;
+                    duplicates += outcome.result.duplicates;
+                    if (outcome.result.rejected.length > 0) {
+                        log(`Server rejected ${outcome.result.rejected.length} events: ${outcome.result.rejected[0]?.reason ?? ''}`);
+                    }
+                    continue;
+                }
+                allOk = false;
+                if (outcome.kind === 'too_large')
+                    tooLarge = true;
+                else if (outcome.kind === 'retry') {
+                    retry = {
+                        error: retry?.error ?? outcome.error,
+                        retryAfterMs: Math.max(retry?.retryAfterMs ?? 0, outcome.retryAfterMs ?? 0),
+                    };
+                }
+                else if (outcome.kind === 'poison') {
+                    // The server will never accept these; count strikes so a poison
+                    // batch cannot block the queue indefinitely.
+                    const dropped = this.spool.fail(ids, this.config.upload.max_retries);
+                    log(`Batch permanently rejected: ${errorMessage(outcome.error)}${dropped ? ` (dropped ${dropped})` : ''}`);
+                }
+                else
+                    paused ??= outcome;
+            }
+            if (accepted + duplicates > 0)
+                log(`Uploaded ${accepted} events (${duplicates} duplicates)`);
+            if (tooLarge) {
+                // The batch is too big for the server, but the events are fine.
+                this.batchSize = Math.max(1, Math.floor(this.batchSize / 2));
+                log(`Server rejected the batch as too large — reducing batch size to ${this.batchSize}`);
+            }
+            if (paused) {
+                this.pause(paused);
+                return false;
+            }
+            if (retry !== null) {
+                this.uploadFailures += 1;
+                const wait = Math.max(backoffMs(this.uploadFailures), retry.retryAfterMs);
+                this.nextUploadAt = Date.now() + wait;
+                log(`Upload failed (attempt ${this.uploadFailures}), retrying in ${Math.round(wait / 1000)}s: ${errorMessage(retry.error)}`);
+                return false;
+            }
+            // Settings just changed (413) or strikes were counted: re-enter on the
+            // next tick rather than keep draining with the old shape.
+            if (!allOk)
+                return false;
+            this.uploadFailures = 0;
+            this.resume();
+            // Creep back up after a shrink so one huge session does not permanently
+            // halve throughput.
+            if (this.batchSize < this.maxBatchSize) {
+                this.batchSize = Math.min(this.maxBatchSize, this.batchSize * 2);
+            }
         }
+        return true;
     }
-    /**
-     * Sends one batch. Returns false when the wave should stop.
-     *
-     * Every failure branch is the same policy this had when batches went out one
-     * at a time; only the `return` became `return false`.
-     */
+    /** Sends one batch and reports what happened. Touches no shared state. */
     async sendBatch(batch) {
         try {
             const result = await this.client.sendBatch(batch.map((b) => b.event));
-            // Duplicates are acknowledged too — the server already has them.
-            this.spool.ack(batch.map((b) => b.eventId));
-            this.uploadFailures = 0;
-            // Creep back up after a shrink so one huge session does not permanently
-            // halve throughput.
-            if (this.batchSize < this.config.upload.batch_size) {
-                this.batchSize = Math.min(this.config.upload.batch_size, this.batchSize * 2);
-            }
-            if (result.rejected.length > 0) {
-                log(`Server rejected ${result.rejected.length} events: ${result.rejected[0]?.reason ?? ''}`);
+            const nothingTaken = result.accepted === 0 && result.duplicates === 0 && result.rejected.length >= batch.length;
+            if (nothingTaken) {
+                // The server said 200 but kept nothing. Acking would delete telemetry
+                // it never stored: an over-quota org (retry next month, not never) or
+                // a collector whose schema the server no longer understands.
+                if (result.quota?.exceeded) {
+                    return {
+                        kind: 'paused',
+                        reason: 'quota',
+                        detail: `monthly event quota exceeded (${result.quota.used ?? '?'}/${result.quota.limit ?? '?'})`,
+                    };
+                }
+                // One event the server would not take is that event's fault, not a
+                // collector-wide schema drift: strike it, do not pause the queue.
+                if (batch.length === 1)
+                    return { kind: 'poison', error: new Error(result.rejected[0]?.reason ?? 'rejected') };
+                return {
+                    kind: 'paused',
+                    reason: 'schema',
+                    detail: `server rejected every event (${result.rejected[0]?.reason ?? ''}) — collector ${VERSION} may be out of date`,
+                };
             }
-            log(`Uploaded ${result.accepted} events (${result.duplicates} duplicates)`);
-            return true;
+            return { kind: 'ok', result };
         }
         catch (error) {
-            const status = error instanceof Error && 'status' in error ? Number(error.status) : 0;
-            // 413: the batch is too big for the server, but the events are fine.
-            // Halve and retry rather than treat real telemetry as poison.
-            if (status === 413 && this.batchSize > 1) {
-                this.batchSize = Math.max(1, Math.floor(this.batchSize / 2));
-                log(`Server rejected the batch as too large — reducing batch size to ${this.batchSize}`);
-                return false;
-            }
-            const retryable = error instanceof Error && 'retryable' in error ? Boolean(error.retryable) : true;
-            if (!retryable) {
-                // The server will never accept these; count strikes so a poison
-                // batch cannot block the queue indefinitely.
-                const dropped = this.spool.fail(batch.map((b) => b.eventId), this.config.upload.max_retries);
-                log(`Batch permanently rejected: ${errorMessage(error)}${dropped ? ` (dropped ${dropped})` : ''}`);
-                return false;
-            }
-            this.uploadFailures += 1;
-            const wait = backoffMs(this.uploadFailures);
-            log(`Upload failed (attempt ${this.uploadFailures}), retrying in ${Math.round(wait / 1000)}s: ${errorMessage(error)}`);
-            await sleep(wait);
-            return false;
+            if (!(error instanceof ApiError))
+                return { kind: 'retry', error };
+            // The key is revoked or lacks ingest: the events are fine, the login is not.
+            if (error.status === 401 || error.status === 403)
+                return { kind: 'paused', reason: 'auth', detail: error.message };
+            // Too big for the server but the events are fine — unless it is a
+            // single event, which then really is unacceptable.
+            if (error.status === 413)
+                return batch.length > 1 ? { kind: 'too_large' } : { kind: 'poison', error };
+            if (error.retryable)
+                return { kind: 'retry', error, retryAfterMs: error.retryAfterMs };
+            return { kind: 'poison', error };
+        }
+    }
+    /** Backs off and records why, once per reason, where `agentstrack status` can read it. */
+    pause(p) {
+        this.uploadFailures += 1;
+        this.nextUploadAt = Date.now() + backoffMs(this.uploadFailures);
+        if (this.pausedReason !== p.reason) {
+            this.pausedReason = p.reason;
+            log(`Uploads paused (${p.reason}): ${p.detail}`);
         }
+        this.spool.setMeta(UPLOAD_PAUSE_META, `${p.reason}: ${p.detail}`);
+    }
+    resume() {
+        if (!this.pausedReason)
+            return;
+        log(`Uploads resumed after ${this.pausedReason} pause`);
+        this.pausedReason = null;
+        this.spool.deleteMeta(UPLOAD_PAUSE_META);
     }
     async reportHealth() {
         if (!this.config.collector_id)
@@ -389,6 +611,7 @@ export class Collector {
         try {
             const agents = await Promise.all(this.adapters.map(async (a) => ({ agent: a.id, version: (await a.detect()).version })));
             await this.client.health({
+                ...machineInfo(),
                 collector_id: this.config.collector_id,
                 queue_depth: this.spool.depth(),
                 version: VERSION,
@@ -403,8 +626,16 @@ export class Collector {
     queueDepth() {
         return this.spool.depth();
     }
+    /** Upload policy state, for tests and diagnostics. */
+    uploadState() {
+        return {
+            failures: this.uploadFailures,
+            batchSize: this.batchSize,
+            nextUploadAt: this.nextUploadAt,
+            paused: this.pausedReason,
+        };
+    }
 }
-export const VERSION = '0.1.0';
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }