@sapiom/harness 0.1.1 → 0.1.2

package/dist/core/collector/analytics-emitter.js

@@ -0,0 +1,131 @@
+/**
+ * Harness remote telemetry emitter — a thin adapter that bridges the
+ * harness-internal `AnalyticsEvent` shape into `@sapiom/analytics-core`'s
+ * `track()` API, forwarding events to the hosted collector at
+ * `POST /v1/analytics/collector`.
+ *
+ * Design contract:
+ * - ONE analytics-core instance per harness server process. Multiple
+ *   concurrent harness sessions are multiplexed onto it via per-event
+ *   `session_id` overrides — no timer/listener multiplication.
+ * - Consent is wired via the `disabled` flag on the analytics instance.
+ *   When the settings toggle changes, the current instance is shut down and
+ *   a new one is created with the updated flag.
+ * - The local ndjson store (store.ts) is written ALWAYS, independent of
+ *   consent; this emitter gates only the remote collector path.
+ * - `SAPIOM_TELEMETRY_DISABLED=1` and `DO_NOT_TRACK=1` are honored by
+ *   analytics-core's own consent resolution, at highest precedence.
+ * - Event shape follows the harness convergence additions in the collector
+ *   contract: `data.seq`, `data.context`, `data.harness_session_id`,
+ *   `data.agent_session_id`, `data.harness_kind`, `source: "harness"`.
+ */
+import { createAnalytics, SAPIOM_COLLECTOR_ENDPOINT, } from "@sapiom/analytics-core";
+/**
+ * Build the `data` payload that analytics-core will send for a harness
+ * analytics event. The harness contract adds:
+ *   - `seq`               — monotonic per session, producer-assigned
+ *   - `context`           — {app_version, os, arch, node} per event
+ *   - `harness_session_id` — first-class analysis dimension
+ *   - `agent_session_id`  — first-class analysis dimension (null if unknown)
+ *   - `harness_kind`      — first-class analysis dimension
+ * Plus the event's own free-form `payload` is merged in.
+ */
+function buildEventData(event, context) {
+    return {
+        ...event.payload,
+        seq: event.seq,
+        harness_session_id: event.harnessSessionId,
+        agent_session_id: event.agentSessionId ?? null,
+        harness_kind: event.harness,
+        ...(event.tenantId !== null ? { tenant_id: event.tenantId } : {}),
+        context: {
+            app_version: context.harnessVersion,
+            os: context.os,
+            arch: context.arch,
+            node: context.nodeVersion,
+        },
+    };
+}
+function buildConfig(options, telemetryOptIn, apiKey) {
+    return {
+        source: "harness",
+        sdkName: options.sdkName,
+        sdkVersion: options.sdkVersion,
+        // Point at the live collector; SAPIOM_ANALYTICS_ENDPOINT env override
+        // (used in tests) takes precedence inside analytics-core's resolveEndpoint.
+        endpoint: options.endpoint ?? SAPIOM_COLLECTOR_ENDPOINT,
+        apiKey: apiKey ?? undefined,
+        fetchImpl: options.fetchImpl,
+        debug: options.onDebug
+            ? (message, detail) => {
+                const msg = detail !== undefined ? `${message}: ${String(detail)}` : message;
+                options.onDebug(msg);
+            }
+            : undefined,
+        // Consent: the `disabled` flag gates the entire instance. When the
+        // harness settings toggle changes, setTelemetryOptIn() shuts down the
+        // current instance and creates a new one. Env flags (SAPIOM_TELEMETRY_DISABLED /
+        // DO_NOT_TRACK) are checked by analytics-core at highest precedence, so
+        // they always override the stored consent state.
+        disabled: !telemetryOptIn,
+    };
+}
+export function createHarnessEmitter(options) {
+    let telemetryOptIn = options.telemetryOptIn;
+    let apiKey = options.apiKey ?? null;
+    let analytics = createAnalytics(buildConfig(options, telemetryOptIn, apiKey));
+    function recreate(discardPrevQueue = false) {
+        // Install the new instance synchronously so enqueue() calls that arrive
+        // during the async shutdown drain land on the correct new instance.
+        const prev = analytics;
+        analytics = createAnalytics(buildConfig(options, telemetryOptIn, apiKey));
+        if (discardPrevQueue) {
+            // Privacy-sensitive direction (opt-OUT): the user revoked consent —
+            // discard buffered events before shutdown so they are not delivered.
+            // In-flight sends (already on the wire) still complete normally;
+            // only the in-memory buffer is dropped.
+            prev.discard?.();
+        }
+        // The void is intentional: callers don't await this path and
+        // analytics-core guarantees shutdown() never rejects.
+        void prev.shutdown();
+    }
+    return {
+        enqueue(event) {
+            analytics.track(event.type, buildEventData(event, options.context), {
+                // Per-event session override: the harness server hosts multiple
+                // concurrent sessions; each event carries its own session_id so
+                // the single analytics instance can multiplex them correctly.
+                session_id: event.harnessSessionId,
+                event_id: event.eventId,
+            });
+        },
+        setTelemetryOptIn(optIn) {
+            if (telemetryOptIn === optIn)
+                return;
+            const wasOptedIn = telemetryOptIn;
+            telemetryOptIn = optIn;
+            // Recreate the instance with the updated consent state. The new
+            // instance is installed synchronously so subsequent enqueue() calls
+            // see it immediately.
+            // Opting OUT: discard any buffered events — the user revoked consent,
+            // so delivering them would violate their intent. Opting IN (or rotating
+            // the apiKey): drain gracefully; those aren't privacy-sensitive.
+            recreate(wasOptedIn && !optIn);
+        },
+        setApiKey(key) {
+            if (apiKey === key)
+                return;
+            apiKey = key;
+            // Recreate with the new key. Drain gracefully (not a consent change).
+            recreate(false);
+        },
+        async flush() {
+            await analytics.flush();
+        },
+        async close() {
+            await analytics.shutdown();
+        },
+    };
+}
+//# sourceMappingURL=analytics-emitter.js.map

package/dist/core/collector/analytics-emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics-emitter.js","sourceRoot":"","sources":["../../../src/core/collector/analytics-emitter.ts"],"names":[],"mappings":"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"}

package/dist/core/collector/identity-migration.d.ts

@@ -0,0 +1,25 @@
+/**
+ * One-way identity migration: seed `~/.sapiom/analytics.json` from the
+ * harness's legacy `~/.sapiom/harness/machine-id` when analytics.json does
+ * not yet exist. Idempotent: a subsequent call after analytics.json exists is
+ * always a no-op.
+ *
+ * Purpose: existing installs of harness 0.1.x had a stable anonymous id in
+ * the harness-specific machine-id file. Seeding the canonical analytics.json
+ * from that value preserves the longitudinal join key so prior sessions stay
+ * attributable to the same install after the upgrade.
+ *
+ * Contract:
+ * - Reads machine-id only if analytics.json is absent (avoids file-system
+ *   I/O on the hot path for already-migrated installs).
+ * - Never throws; degrades silently on any I/O failure (unwritable HOME, etc.)
+ * - Call once at harness server boot, before the analytics emitter is created
+ *   (so the emitter's IdentityStore finds the seeded file on first track()).
+ */
+/**
+ * @param legacyMachineIdPath Absolute path to `~/.sapiom/harness/machine-id`.
+ * @param analyticsJsonPath Absolute path to `~/.sapiom/analytics.json`.
+ *   Defaults to the canonical location.
+ */
+export declare function migrateHarnessIdentity(legacyMachineIdPath: string, analyticsJsonPath?: string): Promise<void>;
+//# sourceMappingURL=identity-migration.d.ts.map

package/dist/core/collector/identity-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-migration.d.ts","sourceRoot":"","sources":["../../../src/core/collector/identity-migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAiBH;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,mBAAmB,EAAE,MAAM,EAC3B,iBAAiB,CAAC,EAAE,MAAM,GACzB,OAAO,CAAC,IAAI,CAAC,CAiCf"}

package/dist/core/collector/identity-migration.js

@@ -0,0 +1,68 @@
+/**
+ * One-way identity migration: seed `~/.sapiom/analytics.json` from the
+ * harness's legacy `~/.sapiom/harness/machine-id` when analytics.json does
+ * not yet exist. Idempotent: a subsequent call after analytics.json exists is
+ * always a no-op.
+ *
+ * Purpose: existing installs of harness 0.1.x had a stable anonymous id in
+ * the harness-specific machine-id file. Seeding the canonical analytics.json
+ * from that value preserves the longitudinal join key so prior sessions stay
+ * attributable to the same install after the upgrade.
+ *
+ * Contract:
+ * - Reads machine-id only if analytics.json is absent (avoids file-system
+ *   I/O on the hot path for already-migrated installs).
+ * - Never throws; degrades silently on any I/O failure (unwritable HOME, etc.)
+ * - Call once at harness server boot, before the analytics emitter is created
+ *   (so the emitter's IdentityStore finds the seeded file on first track()).
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import { seedAnalyticsIdentity } from "@sapiom/analytics-core";
+const UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function resolveHomeDir() {
+    const fromEnv = process.env.HOME || process.env.USERPROFILE;
+    if (typeof fromEnv === "string" && fromEnv.length > 0)
+        return fromEnv;
+    return os.homedir();
+}
+/**
+ * @param legacyMachineIdPath Absolute path to `~/.sapiom/harness/machine-id`.
+ * @param analyticsJsonPath Absolute path to `~/.sapiom/analytics.json`.
+ *   Defaults to the canonical location.
+ */
+export async function migrateHarnessIdentity(legacyMachineIdPath, analyticsJsonPath) {
+    try {
+        const targetPath = analyticsJsonPath ??
+            path.join(resolveHomeDir(), ".sapiom", "analytics.json");
+        // analytics.json already exists — nothing to migrate.
+        try {
+            await fs.access(targetPath);
+            return;
+        }
+        catch {
+            // File doesn't exist — proceed to migration attempt.
+        }
+        // Read the legacy machine-id.
+        let machineId;
+        try {
+            machineId = (await fs.readFile(legacyMachineIdPath, "utf8")).trim();
+        }
+        catch {
+            // Legacy file doesn't exist (fresh install) — let analytics-core
+            // generate a new id naturally on first track().
+            return;
+        }
+        // Validate shape: a non-UUID machine-id shouldn't be propagated.
+        if (!UUID_SHAPE.test(machineId))
+            return;
+        // Seed analytics.json. seedAnalyticsIdentity handles atomic write +
+        // 0600 permissions + degrade-on-error.
+        seedAnalyticsIdentity(machineId);
+    }
+    catch {
+        // Migration failures must never crash the server.
+    }
+}
+//# sourceMappingURL=identity-migration.js.map

package/dist/core/collector/identity-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-migration.js","sourceRoot":"","sources":["../../../src/core/collector/identity-migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9B,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,MAAM,UAAU,GACd,iEAAiE,CAAC;AAEpE,SAAS,cAAc;IACrB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IAC5D,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IACtE,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,mBAA2B,EAC3B,iBAA0B;IAE1B,IAAI,CAAC;QACH,MAAM,UAAU,GACd,iBAAiB;YACjB,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,gBAAgB,CAAC,CAAC;QAE3D,sDAAsD;QACtD,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YAC5B,OAAO;QACT,CAAC;QAAC,MAAM,CAAC;YACP,qDAAqD;QACvD,CAAC;QAED,8BAA8B;QAC9B,IAAI,SAAiB,CAAC;QACtB,IAAI,CAAC;YACH,SAAS,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACtE,CAAC;QAAC,MAAM,CAAC;YACP,iEAAiE;YACjE,gDAAgD;YAChD,OAAO;QACT,CAAC;QAED,iEAAiE;QACjE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,OAAO;QAExC,oEAAoE;QACpE,uCAAuC;QACvC,qBAAqB,CAAC,SAAS,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,kDAAkD;IACpD,CAAC;AACH,CAAC"}

package/dist/core/collector/store-retention.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Retention cap enforcement for the local analytics sink (events.ndjson).
+ *
+ * Policy (enforced on server boot and periodically afterwards):
+ *   - Size cap: 50 MB — truncate to the newest events that fit.
+ *   - Age cap: 30 days — drop events older than this by their `ts` field.
+ *   The stricter of the two wins; oldest-first truncation always preserves
+ *   the newest events.
+ *
+ * Atomicity: rewrites happen via a temp-file rename so a crash mid-write
+ * never leaves a corrupt or empty events file. The write path must be in
+ * the same directory (same filesystem partition) as the target so rename()
+ * is atomic.
+ *
+ * Concurrency: callers MUST run sweepNdjson() through EventStore.runExclusive()
+ * so the sweep's read→filter→rename window never races a concurrent append.
+ * The store serializes all appends through a promise queue; runExclusive()
+ * chains the sweep onto that same queue, guaranteeing mutual exclusion.
+ * See store.ts and server/index.ts for the wiring.
+ *
+ * Corruption tolerance: lines that fail JSON.parse are silently kept rather
+ * than aborting the sweep — a single bad line never blocks retention.
+ */
+/** 50 MB default size cap. */
+export declare const DEFAULT_MAX_SIZE_BYTES: number;
+/** 30 days default age cap. */
+export declare const DEFAULT_MAX_AGE_MS: number;
+export interface SweepOptions {
+    maxSizeBytes?: number;
+    maxAgeMs?: number;
+}
+export interface SweepResult {
+    /** Number of lines in the file before the sweep. */
+    linesBefore: number;
+    /** Number of lines retained after the sweep. */
+    linesAfter: number;
+    /** True when the file was actually rewritten (something was trimmed). */
+    rewritten: boolean;
+}
+/**
+ * Enforces size and age caps on an ndjson file, retaining the newest events.
+ *
+ * Returns a SweepResult describing what happened. Never throws on ENOENT
+ * (the file doesn't exist yet — that's fine). Propagates other I/O errors
+ * to the caller.
+ *
+ * IMPORTANT: callers must run this through EventStore.runExclusive() to
+ * prevent races with concurrent appends (see module-level docstring).
+ */
+export declare function sweepNdjson(filePath: string, options?: SweepOptions): Promise<SweepResult>;
+//# sourceMappingURL=store-retention.d.ts.map

package/dist/core/collector/store-retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-retention.d.ts","sourceRoot":"","sources":["../../../src/core/collector/store-retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,8BAA8B;AAC9B,eAAO,MAAM,sBAAsB,QAAmB,CAAC;AACvD,+BAA+B;AAC/B,eAAO,MAAM,kBAAkB,QAA2B,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CA+EtB"}

package/dist/core/collector/store-retention.js

@@ -0,0 +1,117 @@
+/**
+ * Retention cap enforcement for the local analytics sink (events.ndjson).
+ *
+ * Policy (enforced on server boot and periodically afterwards):
+ *   - Size cap: 50 MB — truncate to the newest events that fit.
+ *   - Age cap: 30 days — drop events older than this by their `ts` field.
+ *   The stricter of the two wins; oldest-first truncation always preserves
+ *   the newest events.
+ *
+ * Atomicity: rewrites happen via a temp-file rename so a crash mid-write
+ * never leaves a corrupt or empty events file. The write path must be in
+ * the same directory (same filesystem partition) as the target so rename()
+ * is atomic.
+ *
+ * Concurrency: callers MUST run sweepNdjson() through EventStore.runExclusive()
+ * so the sweep's read→filter→rename window never races a concurrent append.
+ * The store serializes all appends through a promise queue; runExclusive()
+ * chains the sweep onto that same queue, guaranteeing mutual exclusion.
+ * See store.ts and server/index.ts for the wiring.
+ *
+ * Corruption tolerance: lines that fail JSON.parse are silently kept rather
+ * than aborting the sweep — a single bad line never blocks retention.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+/** 50 MB default size cap. */
+export const DEFAULT_MAX_SIZE_BYTES = 50 * 1024 * 1024;
+/** 30 days default age cap. */
+export const DEFAULT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Enforces size and age caps on an ndjson file, retaining the newest events.
+ *
+ * Returns a SweepResult describing what happened. Never throws on ENOENT
+ * (the file doesn't exist yet — that's fine). Propagates other I/O errors
+ * to the caller.
+ *
+ * IMPORTANT: callers must run this through EventStore.runExclusive() to
+ * prevent races with concurrent appends (see module-level docstring).
+ */
+export async function sweepNdjson(filePath, options = {}) {
+    const maxSizeBytes = options.maxSizeBytes ?? DEFAULT_MAX_SIZE_BYTES;
+    const maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    const cutoffMs = Date.now() - maxAgeMs;
+    let content;
+    try {
+        content = await fs.readFile(filePath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return { linesBefore: 0, linesAfter: 0, rewritten: false };
+        }
+        throw err;
+    }
+    const rawLines = content.split("\n");
+    // Last line is often empty (trailing newline) — exclude it from the count.
+    const lines = rawLines[rawLines.length - 1] === "" ? rawLines.slice(0, -1) : rawLines;
+    const linesBefore = lines.length;
+    // Filter by age first — drop lines whose `ts` field is older than the cap.
+    // Lines that fail JSON.parse are kept (corrupted lines fall through the age
+    // filter; the size cap below may still drop them if needed).
+    const ageFiltered = lines.filter((line) => {
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.ts !== "string")
+                return true; // keep if no ts
+            const lineMs = Date.parse(parsed.ts);
+            return !Number.isNaN(lineMs) && lineMs >= cutoffMs;
+        }
+        catch {
+            return true; // keep on parse failure
+        }
+    });
+    // Size cap: O(n) cumulative-bytes pass — compute the byte length of each
+    // line (with its trailing newline), accumulate from the BACK (newest first),
+    // and find the earliest index that still fits in maxSizeBytes. Avoids the
+    // O(n²) cost of re-joining the entire array on each iteration.
+    let dropCount = 0;
+    if (ageFiltered.length > 0) {
+        // Total byte count of all age-filtered lines.
+        const lineLengths = ageFiltered.map((line) => Buffer.byteLength(line + "\n", "utf8"));
+        const total = lineLengths.reduce((sum, n) => sum + n, 0);
+        if (total > maxSizeBytes) {
+            // Walk from the front, accumulating bytes to drop until the remaining
+            // content (total − dropped) fits within the cap.
+            let dropped = 0;
+            for (let i = 0; i < ageFiltered.length; i++) {
+                if (total - dropped <= maxSizeBytes)
+                    break;
+                dropped += lineLengths[i];
+                dropCount = i + 1;
+            }
+        }
+    }
+    const kept = dropCount > 0 ? ageFiltered.slice(dropCount) : ageFiltered;
+    const linesAfter = kept.length;
+    const nothingChanged = linesAfter === linesBefore;
+    if (nothingChanged) {
+        return { linesBefore, linesAfter, rewritten: false };
+    }
+    // Atomic rewrite via temp file + rename. Both must be on the same filesystem
+    // (same directory) for the rename to be atomic.
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    const tmpPath = path.join(dir, `.events-retention-tmp-${process.pid}-${Date.now()}.ndjson`);
+    try {
+        const newContent = kept.length === 0 ? "" : kept.join("\n") + "\n";
+        await fs.writeFile(tmpPath, newContent, "utf8");
+        await fs.rename(tmpPath, filePath);
+    }
+    catch (err) {
+        // Best-effort cleanup of the temp file; the rename failure is what matters.
+        await fs.unlink(tmpPath).catch(() => undefined);
+        throw err;
+    }
+    return { linesBefore, linesAfter, rewritten: true };
+}
+//# sourceMappingURL=store-retention.js.map

package/dist/core/collector/store-retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-retention.js","sourceRoot":"","sources":["../../../src/core/collector/store-retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,8BAA8B;AAC9B,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACvD,+BAA+B;AAC/B,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAgB3D;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAgB,EAChB,UAAwB,EAAE;IAE1B,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,sBAAsB,CAAC;IACpE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,kBAAkB,CAAC;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC;IAEvC,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAChD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACrD,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAC7D,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrC,2EAA2E;IAC3E,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IACtF,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC;IAEjC,2EAA2E;IAC3E,4EAA4E;IAC5E,6DAA6D;IAC7D,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QACxC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAqB,CAAC;YACpD,IAAI,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC,CAAC,gBAAgB;YAChE,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACrC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,QAAQ,CAAC;QACrD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC,CAAC,wBAAwB;QACvC,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,yEAAyE;IACzE,6EAA6E;IAC7E,0EAA0E;IAC1E,+DAA+D;IAC/D,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,8CAA8C;QAC9C,MAAM,WAAW,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QACtF,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAEzD,IAAI,KAAK,GAAG,YAAY,EAAE,CAAC;YACzB,sEAAsE;YACtE,iDAAiD;YACjD,IAAI,OAAO,GAAG,CAAC,CAAC;YAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC5C,IAAI,KAAK,GAAG,OAAO,IAAI,YAAY;oBAAE,MAAM;gBAC3C,OAAO,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC;gBAC1B,SAAS,GAAG,CAAC,GAAG,CAAC,CAAC;YACpB,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;IAExE,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC;IAC/B,MAAM,cAAc,GAAG,UAAU,KAAK,WAAW,CAAC;IAClD,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACvD,CAAC;IAED,6EAA6E;IAC7E,gDAAgD;IAChD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,yBAAyB,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAC5F,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QACnE,MAAM,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;QAChD,MAAM,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,4EAA4E;QAC5E,MAAM,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAChD,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AACtD,CAAC"}

package/dist/core/collector/store.d.ts

@@ -2,11 +2,27 @@
  * Append-only local sink for analytics events. Always written, regardless
  * of telemetry opt-in — this is the "demo inspects this" local debug file,
  * independent of whether anything gets batched to a remote collector.
+ *
+ * Concurrency: every append is serialized through a promise queue (the same
+ * pattern as workflow-registry.ts and session-manager.ts). `runExclusive(fn)`
+ * chains `fn` onto the same queue so retention sweeps (read→filter→rename)
+ * never overlap with an in-flight append and no appended line can be lost
+ * in a sweep's read window. Overhead is negligible — appends are low-frequency
+ * (one per hook event), and the queue never holds more than O(sessions) entries.
  */
 import { type AnalyticsEvent } from "../../shared/types.js";
 export interface EventStore {
-    /** Append one event as a single ndjson line. Crash-safe (fs.appendFile). */
+    /** Append one event as a single ndjson line, serialized through the queue. */
     append(event: AnalyticsEvent): Promise<void>;
+    /**
+     * Run `fn` exclusively — after all pending appends complete and blocking
+     * any new appends until `fn` resolves. Use this to run a retention sweep
+     * without racing concurrent writes.
+     *
+     * A failed `fn` never poisons the queue (later appends proceed normally).
+     * The return value of `fn` is forwarded to the caller.
+     */
+    runExclusive<T>(fn: () => Promise<T>): Promise<T>;
 }
 /**
  * @param filePath Defaults to `HARNESS_PATHS.events`

package/dist/core/collector/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/core/collector/store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG3E,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,GAAE,MAA6B,GAAG,UAAU,CAiBpF"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/core/collector/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG3E,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C;;;;;;;OAOG;IACH,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACnD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,GAAE,MAA6B,GAAG,UAAU,CAqCpF"}

package/dist/core/collector/store.js

@@ -2,6 +2,13 @@
  * Append-only local sink for analytics events. Always written, regardless
  * of telemetry opt-in — this is the "demo inspects this" local debug file,
  * independent of whether anything gets batched to a remote collector.
+ *
+ * Concurrency: every append is serialized through a promise queue (the same
+ * pattern as workflow-registry.ts and session-manager.ts). `runExclusive(fn)`
+ * chains `fn` onto the same queue so retention sweeps (read→filter→rename)
+ * never overlap with an in-flight append and no appended line can be lost
+ * in a sweep's read window. Overhead is negligible — appends are low-frequency
+ * (one per hook event), and the queue never holds more than O(sessions) entries.
  */
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
@@ -20,10 +27,24 @@ export function createEventStore(filePath = HARNESS_PATHS.events) {
         }
         return dirReady;
     }
+    // Promise queue — same pattern as workflow-registry.ts:106-135.
+    // Chains each operation so they execute strictly one-at-a-time.
+    // A failed run never poisons subsequent operations.
+    let queue = Promise.resolve();
+    function enqueue(run) {
+        const next = queue.catch(() => { }).then(run);
+        queue = next.then(() => { }, () => { });
+        return next;
+    }
     return {
-        async append(event) {
-            await ensureDir();
-            await fs.appendFile(resolvedPath, `${JSON.stringify(event)}\n`, "utf8");
+        append(event) {
+            return enqueue(async () => {
+                await ensureDir();
+                await fs.appendFile(resolvedPath, `${JSON.stringify(event)}\n`, "utf8");
+            });
+        },
+        runExclusive(fn) {
+            return enqueue(fn);
         },
     };
 }

package/dist/core/collector/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/core/collector/store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,aAAa,EAAuB,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAOzC;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAmB,aAAa,CAAC,MAAM;IACtE,MAAM,YAAY,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC1C,IAAI,QAAQ,GAAyB,IAAI,CAAC;IAE1C,SAAS,SAAS;QAChB,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,QAAQ,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC7F,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,KAAqB;YAChC,MAAM,SAAS,EAAE,CAAC;YAClB,MAAM,EAAE,CAAC,UAAU,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC1E,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/core/collector/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,aAAa,EAAuB,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAgBzC;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAmB,aAAa,CAAC,MAAM;IACtE,MAAM,YAAY,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC1C,IAAI,QAAQ,GAAyB,IAAI,CAAC;IAE1C,SAAS,SAAS;QAChB,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,QAAQ,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC7F,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,gEAAgE;IAChE,gEAAgE;IAChE,oDAAoD;IACpD,IAAI,KAAK,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAE7C,SAAS,OAAO,CAAI,GAAqB;QACvC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7C,KAAK,GAAG,IAAI,CAAC,IAAI,CACf,GAAG,EAAE,GAAE,CAAC,EACR,GAAG,EAAE,GAAE,CAAC,CACT,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,MAAM,CAAC,KAAqB;YAC1B,OAAO,OAAO,CAAC,KAAK,IAAI,EAAE;gBACxB,MAAM,SAAS,EAAE,CAAC;gBAClB,MAAM,EAAE,CAAC,UAAU,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC1E,CAAC,CAAC,CAAC;QACL,CAAC;QAED,YAAY,CAAI,EAAoB;YAClC,OAAO,OAAO,CAAC,EAAE,CAAC,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/errors.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Typed errors for session and spawn failures. Each carries a stable `code`
+ * so callers can react programmatically to specific failure modes instead of
+ * parsing error message strings.
+ *
+ * HTTP mappings (server/rest.ts, server/macros.ts):
+ *   UnknownSessionError       → 404
+ *   SessionNotReadyError      → 409
+ *   SessionAlreadyLiveError   → 409
+ *   SessionNotResumeableError → 409
+ *   AdapterNotFoundError      → 400
+ */
+/** Base class for all typed harness errors. */
+export declare class HarnessError extends Error {
+    /** Stable machine-readable code callers can branch on without parsing messages. */
+    readonly code: string;
+    /** Underlying error, when this error wraps another. */
+    readonly cause?: unknown;
+    constructor(code: string, message: string, cause?: unknown);
+}
+/**
+ * Thrown when an operation references a session id that does not exist in the
+ * registry. Maps to HTTP 404.
+ */
+export declare class UnknownSessionError extends HarnessError {
+    constructor(id: string);
+}
+/**
+ * Thrown by `submitInput()` when a session's pty is alive but never became
+ * interactive within the grace period — the trust-dialog race this readiness
+ * mechanism exists to catch. Maps to HTTP 409.
+ */
+export declare class SessionNotReadyError extends HarnessError {
+    constructor(id: string);
+}
+/**
+ * Thrown by `resume()` when the session record has no `agentSessionId` to
+ * resume from (it was never fully started, or is history-only with no
+ * recorded session). Maps to HTTP 409.
+ */
+export declare class SessionNotResumeableError extends HarnessError {
+    constructor(id: string);
+}
+/**
+ * Thrown by `resume()` when the session already has a live pty — double-resume
+ * is a no-op caller error. Maps to HTTP 409.
+ */
+export declare class SessionAlreadyLiveError extends HarnessError {
+    constructor(id: string);
+}
+/**
+ * Thrown when an operation requires a harness adapter that has not been
+ * registered. Maps to HTTP 400.
+ */
+export declare class AdapterNotFoundError extends HarnessError {
+    constructor(harness: string);
+}
+/**
+ * Thrown when a spawn or send operation is attempted on an external-mode
+ * harness adapter (e.g. Conductor) whose sessions are managed by its own
+ * companion app — the harness cannot spawn or inject into them. Maps to
+ * HTTP 409.
+ *
+ * The `harness` field names the adapter so the UI can show a targeted message
+ * (e.g. "Conductor sessions are managed by the Conductor app").
+ */
+export declare class ExternalHarnessError extends HarnessError {
+    readonly harness: string;
+    constructor(harness: string, label: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,+CAA+C;AAC/C,qBAAa,YAAa,SAAQ,KAAK;IACrC,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEb,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAQ3D;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;gBACvC,EAAE,EAAE,MAAM;CAGvB;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,EAAE,EAAE,MAAM;CAMvB;AAED;;;;GAIG;AACH,qBAAa,yBAA0B,SAAQ,YAAY;gBAC7C,EAAE,EAAE,MAAM;CAGvB;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,YAAY;gBAC3C,EAAE,EAAE,MAAM;CAGvB;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,OAAO,EAAE,MAAM;CAG5B;AAED;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAO3C"}