@agentsfleet/orly 0.6.9 → 0.7.1

package/skills/orly-write-integration-test/SKILL.md

@@ -11,6 +11,12 @@ description: >
 
 # Write Integration Test
 
+At invocation start, record the consent-gated usage signal without blocking the skill:
+
+```bash
+command -v orly >/dev/null 2>&1 && ORLY_INVOCATION=skill orly skill-event orly-write-integration-test >/dev/null 2>&1 || true
+```
+
 Service-layer tests that prove real wiring works under real failure modes. Sits between unit tests (`make test`) and browser E2E (gstack `/qa`, `/e2e-qa-playwright`).
 
 > **What this guarantees / what it doesn't.** Integration tests don't prove "zero bugs

package/skills/orly-write-unit-test/SKILL.md

@@ -11,6 +11,12 @@ description: >
 
 # Write Unit Test
 
+At invocation start, record the consent-gated usage signal without blocking the skill:
+
+```bash
+command -v orly >/dev/null 2>&1 && ORLY_INVOCATION=skill orly skill-event orly-write-unit-test >/dev/null 2>&1 || true
+```
+
 Generate tests that catch bugs before they ship. Tests run *during* implementation, not after.
 
 > **What this guarantees / what it doesn't.** No test suite proves "zero bugs in

package/src/cli.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
-import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 
 const ROOT = resolve(import.meta.dir, "..");
 const COMMAND = resolve(ROOT, "bin/orly");
@@ -18,6 +18,19 @@ describe("orly command", () => {
     expect(output).not.toContain("oracle-rules");
   });
 
+  test("telemetry_help_names_tiers_storage_and_privacy", () => {
+    const result = Bun.spawnSync([COMMAND, "--help"], { cwd: ROOT, stdout: "pipe", stderr: "pipe" });
+    const output = result.stdout.toString();
+
+    expect(output).toContain("off by default");
+    expect(output).toContain("anonymous");
+    expect(output).toContain("~/.config/agentsfleet/orly/.orly.json");
+    expect(output).toContain("AGENTSFLEET_STATE_DIR");
+    expect(output).toContain("ORLY_TELEMETRY_OFF=1");
+    expect(output).toContain("packaged Orly skill");
+    expect(output).toContain("never collects source, paths, repositories, branches, arguments, prompts");
+  });
+
   // Adversarial review found recordOptIn running before the --dry-run branch,
   // so a preview created .oracle/orly.json — and on an installed repository
   // permanently added the pack. A dry run changes nothing, opt-in included.
@@ -67,4 +80,72 @@ describe("orly command", () => {
 
     expect(result.exitCode).toBe(0);
   });
+
+  test("telemetry_failure_never_changes_command_result", () => {
+    const blockedRoot = join(mkdtempSync(join(tmpdir(), "orly-telemetry-blocked-")), "state-file");
+    writeFileSync(blockedRoot, "not a directory\n");
+    const enabled = { ...process.env, AGENTSFLEET_STATE_DIR: blockedRoot, ORLY_TELEMETRY: "anonymous" };
+    const off = { ...enabled, ORLY_TELEMETRY_OFF: "1" };
+    try {
+      const successWithFailure = Bun.spawnSync([COMMAND, "doctor"], { cwd: ROOT, env: enabled, stdout: "pipe", stderr: "pipe" });
+      const successWithOff = Bun.spawnSync([COMMAND, "doctor"], { cwd: ROOT, env: off, stdout: "pipe", stderr: "pipe" });
+      const errorWithFailure = Bun.spawnSync([COMMAND, "gate", "nope"], { cwd: ROOT, env: enabled, stdout: "pipe", stderr: "pipe" });
+      const errorWithOff = Bun.spawnSync([COMMAND, "gate", "nope"], { cwd: ROOT, env: off, stdout: "pipe", stderr: "pipe" });
+
+      expect(successWithFailure.exitCode).toBe(successWithOff.exitCode);
+      expect(successWithFailure.stdout.toString()).toBe(successWithOff.stdout.toString());
+      expect(errorWithFailure.exitCode).toBe(errorWithOff.exitCode);
+      expect(errorWithFailure.stderr.toString()).toBe(errorWithOff.stderr.toString());
+    } finally {
+      rmSync(dirname(blockedRoot), { recursive: true, force: true });
+    }
+  });
+
+  test("gate_command_records_its_selected_gate_and_failed_criterion", async () => {
+    const root = mkdtempSync(join(tmpdir(), "orly-telemetry-command-"));
+    const repo = join(root, "repo");
+    const stateRoot = join(root, "state");
+    Bun.spawnSync(["git", "init", "-q", repo]);
+    writeFileSync(join(repo, "README.md"), "fixture\n");
+    Bun.spawnSync(["git", "-C", repo, "add", "README.md"]);
+    Bun.spawnSync(["git", "-C", repo, "-c", "user.name=Orly Test", "-c", "user.email=orly@example.invalid", "commit", "-q", "-m", "test: seed"]);
+    Bun.spawnSync(["git", "-C", repo, "checkout", "-q", "-b", "feat/telemetry"]);
+    const env = {
+      ...process.env,
+      AGENTSFLEET_STATE_DIR: stateRoot,
+      ORLY_TELEMETRY: "anonymous",
+      ORLY_TELEMETRY_OFF: "0",
+      ORLY_POSTHOG_HOST: "http://127.0.0.1:1",
+    };
+    try {
+      const result = Bun.spawnSync([COMMAND, "gate", "pr"], { cwd: repo, env, stdout: "pipe", stderr: "pipe" });
+      expect(result.exitCode).toBe(1);
+      const failedCriterion = result.stdout.toString().match(/🔴 ([^:]+):/)?.[1];
+      expect(failedCriterion).toBeDefined();
+
+      const spool = join(stateRoot, "orly/analytics/orly-usage.jsonl");
+      for (let attempt = 0; attempt < 20 && !existsSync(spool); attempt += 1) await Bun.sleep(10);
+      const event = JSON.parse(readFileSync(spool, "utf8"));
+      expect(event).toMatchObject({ command: "gate", gate: "pr", outcome: "error", failed_criterion: failedCriterion });
+      expect(event.duration_ms).toBeGreaterThanOrEqual(0);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("skill_event_accepts_only_packaged_skills", () => {
+    const env = { ...process.env, ORLY_TELEMETRY_OFF: "1", ORLY_INVOCATION: "skill" };
+    const packagedSkills = ["orly-babysit-prs", "orly-spec-new", "orly-write-integration-test", "orly-write-unit-test"];
+    for (const skill of packagedSkills) {
+      const accepted = Bun.spawnSync([COMMAND, "skill-event", skill], { cwd: ROOT, env, stdout: "pipe", stderr: "pipe" });
+      expect(accepted.exitCode).toBe(0);
+      expect(accepted.stdout.toString()).toBe("");
+      expect(readFileSync(join(ROOT, "skills", skill, "SKILL.md"), "utf8")).toContain(`orly skill-event ${skill}`);
+    }
+    const rejected = Bun.spawnSync([COMMAND, "skill-event", "other-skill"], { cwd: ROOT, env, stdout: "pipe", stderr: "pipe" });
+
+    expect(rejected.exitCode).toBe(1);
+    expect(rejected.stderr.toString()).toContain("skill-event requires a packaged Orly skill name");
+    expect(Bun.spawnSync([COMMAND, "--help"], { cwd: ROOT, env, stdout: "pipe" }).stdout.toString()).not.toContain("skill-event");
+  });
 });

package/src/cli.ts

@@ -7,8 +7,11 @@ import { GateReport, isGateName, recordOverride, runGate, runGates } from "./gat
 import { install, InstallResult } from "./install";
 import { isString, OrlyError, readJsonObject, RulesModel } from "./model";
 import { Renderer } from "./render";
+import { beginTelemetry, installedOrlyVersion, isTelemetrySkill, recordTelemetry } from "./telemetry";
 import { verifyRenders, writeEvidence } from "./verify";
 
+type CliResult = { exitCode: number; gate?: string; failedCriterion?: string };
+
 const PASS_RESULT = "pass";
 const NOT_REQUIRED_RESULT = "not-required";
 const ACCEPT_DIRTY_FLAG = "--accept-dirty";
@@ -26,42 +29,61 @@ const FAIL_GLYPH = "🔴";
 const PR_GATE = "pr";
 const ENGINE_MARKER = "evals/install/run.sh";
 const VERIFY_COMMAND = "verify";
+const SKILL_EVENT_COMMAND = "skill-event";
+const TELEMETRY_CONFIG_KEY = "telemetry";
+const ANONYMOUS_TELEMETRY_CONFIG = JSON.stringify({ [TELEMETRY_CONFIG_KEY]: "anonymous" });
+const OFF_TELEMETRY_CONFIG = JSON.stringify({ [TELEMETRY_CONFIG_KEY]: "off" });
 
 const { root, arguments: commandArguments } = parseRoot(Bun.argv.slice(2));
+const startedAt = performance.now();
+const telemetry = await beginTelemetry(commandArguments);
+const result = await execute(root, commandArguments);
+await recordTelemetry(telemetry, {
+  ...(result.gate ? { gate: result.gate } : {}),
+  outcome: result.exitCode === 0 ? "success" : "error",
+  ...(result.failedCriterion ? { failedCriterion: result.failedCriterion } : {}),
+  durationMs: performance.now() - startedAt,
+  version: await installedOrlyVersion(root),
+});
+process.exit(result.exitCode);
 
-try {
-  const model = await RulesModel.load(root);
-  const exitCode = await run(model, commandArguments);
-  process.exit(exitCode);
-} catch (error) {
-  const message = error instanceof Error ? error.message : String(error);
-  console.error(`orly: ${message}`);
-  process.exit(1);
+async function execute(engineRoot: string, args: string[]): Promise<CliResult> {
+  try {
+    return await run(await RulesModel.load(engineRoot), args);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`orly: ${message}`);
+    return cliResult(1);
+  }
 }
 
-async function run(model: RulesModel, args: string[]): Promise<number> {
+async function run(model: RulesModel, args: string[]): Promise<CliResult> {
   const [command, ...rest] = args;
   if (!command || command === "--help" || command === "-h") {
     printHelp();
-    return command ? 0 : 1;
+    return cliResult(command ? 0 : 1);
   }
-  if (command === "--version" || command === "-v") return printVersion(model);
+  if (command === "--version" || command === "-v") return cliResult(await printVersion(model));
   if (command === "doctor") {
     model.validate();
     requireNoArguments(rest, "doctor checks the installed ruleset: orly doctor");
-    return doctorGlobal(model);
+    return cliResult(await doctorGlobal(model));
   }
-  if (command === "init") return materialise(model, rest, true);
-  if (command === "update") return materialise(model, rest, false);
-  if (command === VERIFY_COMMAND) return verify(model, rest);
+  if (command === "init") return cliResult(await materialise(model, rest, true));
+  if (command === "update") return cliResult(await materialise(model, rest, false));
+  if (command === VERIFY_COMMAND) return cliResult(await verify(model, rest));
   if (command === "gate") return gate(model, rest);
-  if (command === "override") return override(rest);
+  if (command === "override") return cliResult(override(rest));
+  if (command === SKILL_EVENT_COMMAND) {
+    if (rest.length !== 1 || !isTelemetrySkill(rest[0])) throw new OrlyError("skill-event requires a packaged Orly skill name");
+    return cliResult(0);
+  }
   throw new OrlyError(`unknown command: ${command}`);
 }
 
 // Read-only: run every gate in order (stop at the first red group), or one
 // named gate. Nothing is ever written.
-function gate(model: RulesModel, args: string[]): number {
+function gate(model: RulesModel, args: string[]): CliResult {
   const acceptDirty = args.includes(ACCEPT_DIRTY_FLAG);
   const named = args.find((argument) => !argument.startsWith("-"));
   if (named !== undefined && !isGateName(named)) throw new OrlyError(`unknown gate: ${named} (work, verify, pr)`);
@@ -69,7 +91,14 @@ function gate(model: RulesModel, args: string[]): number {
   for (const report of reports) printGate(report);
   const allGreen = reports.every((report) => report.ok);
   if (allGreen && (named === undefined || named === PR_GATE)) console.log(`${PASS_GLYPH} PR boundary open — CHORE(close) is the next motion`);
-  return allGreen ? 0 : 1;
+  const failedReport = reports.find((report) => !report.ok);
+  const failedCriterion = failedReport?.results.find((result) => !result.ok)?.name;
+  const selectedGate = named ?? failedReport?.gate;
+  return {
+    exitCode: allGreen ? 0 : 1,
+    ...(selectedGate ? { gate: selectedGate } : {}),
+    ...(failedCriterion ? { failedCriterion } : {}),
+  };
 }
 
 function override(args: string[]): number {
@@ -254,6 +283,10 @@ function optionalValues(args: string[], name: string): string[] {
   return values;
 }
 
+function cliResult(exitCode: number): CliResult {
+  return { exitCode };
+}
+
 function printHelp(): void {
   console.log(`orly — prove the boundary; carry the rules
 
@@ -281,6 +314,17 @@ Install (the repository is the unit — no checkout of this package required):
                                     against what orly would write today
   orly --version                    the installed package version
 
+Usage telemetry (off by default):
+  Consent file:                     ~/.config/agentsfleet/orly/.orly.json
+  State-root override:              AGENTSFLEET_STATE_DIR
+  Set ${ANONYMOUS_TELEMETRY_CONFIG} to send command, gate, and packaged Orly skill
+  names, outcome, failed criterion, duration, Orly version, operating system, architecture,
+  invocation type, timestamps, and random event, session, and installation IDs.
+  Set ${OFF_TELEMETRY_CONFIG} to write and send nothing.
+  ORLY_TELEMETRY=off|anonymous changes one process; ORLY_TELEMETRY_OFF=1 wins.
+  Orly never collects source, paths, repositories, branches, arguments, prompts,
+  output, environment values, raw errors, or personal and account details.
+
 Ruleset authoring (an orly checkout only — refused from an installed package):
   orly verify                       the rules render the same twice, and the
                                     committed copy matches that render`);

package/src/install.test.ts

@@ -237,7 +237,7 @@ describe("install", () => {
     expect(existsSync(join(repo, "AGENTS.md"))).toBe(false);
   });
 
-  test("--force replaces a hook orly did not write", async () => {
+  test("generated_hooks_mark_telemetry_invocation", async () => {
     const model = await RulesModel.load(ROOT);
     const repo = newRepository();
     await Bun.write(join(repo, ".githooks/pre-commit"), "#!/usr/bin/env bash\necho 'ours'\n");
@@ -245,7 +245,8 @@ describe("install", () => {
     const result = await install(model, { targetRoot: repo, force: true, installHooks: true, orlyVersion: "0.4.0" });
 
     expect(result.ok).toBe(true);
-    expect(await Bun.file(join(repo, ".githooks/pre-commit")).text()).toContain("orly gate work");
+    expect(await Bun.file(join(repo, ".githooks/pre-commit")).text()).toContain("export ORLY_INVOCATION=hook");
+    expect(await Bun.file(join(repo, ".githooks/pre-push")).text()).toContain("export ORLY_INVOCATION=hook");
   });
 
   test("--no-hooks installs the rules over an existing hook without touching it", async () => {

package/src/install.ts

@@ -6,6 +6,7 @@ import { CONFIG_PATH, readConfig, seedConfig, selectPacks, writeConfig } from ".
 import { applyMode, assertWritableInside, hashContent, isBelow, isString, JsonObject, modeLabel, objectArray, objectValue, OrlyError, RulesModel, stringArray } from "./model";
 import { referenceClosureErrors, renderProfileText } from "./references";
 import { Renderer } from "./render";
+import { HOOK_INVOCATION_ENV, HOOK_INVOCATION_VALUE } from "./telemetry";
 
 const AGENTS_FILENAME = "AGENTS.md";
 const ORLY_AGENTS_FILENAME = "AGENTS.orly.md";
@@ -277,12 +278,11 @@ function hookScript(gate: string): string {
     "    exit 1",
     "fi",
     "",
+    `export ${HOOK_INVOCATION_ENV}=${HOOK_INVOCATION_VALUE}`,
     `exec orly gate ${gate}`,
     "",
   ].join("\n");
 }
-
-
 // One entry per target, so two packs naming the same file collapse instead of
 // racing. Two packs naming DIFFERENT sources for one target is a registry bug
 // and stops the install rather than letting pack order decide the winner.

package/src/telemetry.test.ts

@@ -0,0 +1,308 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { TelemetryEvent } from "./telemetry";
+import {
+  beginTelemetry,
+  parseTelemetryEvent,
+  readTelemetrySpool,
+  recordTelemetry,
+  replaceTelemetrySpool,
+  resolveTelemetryConsent,
+  TELEMETRY_PROMPT,
+  withSpoolLock,
+} from "./telemetry";
+import { syncTelemetry } from "./telemetry_sync";
+
+const FIXED_TIME = new Date("2026-08-25T12:00:00.000Z");
+const FIVE_MINUTES_MILLISECONDS = 5 * 60 * 1_000;
+const MAX_SPOOL_BYTES = 10 * 1024 * 1024;
+const STATE_ENV = "AGENTSFLEET_STATE_DIR";
+const ANONYMOUS_ENV = "ORLY_TELEMETRY";
+const PRIVATE_SENTINEL = "private-context-sentinel";
+const temporaryRoots: string[] = [];
+
+afterEach(() => {
+  for (const root of temporaryRoots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("telemetry consent", () => {
+  test("resolves_telemetry_consent_in_precedence_order", () => {
+    expect(resolveTelemetryConsent({ ORLY_TELEMETRY_OFF: "1", ORLY_TELEMETRY: "anonymous" }, "anonymous")).toBe("off");
+    expect(resolveTelemetryConsent({ ORLY_TELEMETRY: "off" }, "anonymous")).toBe("off");
+    expect(resolveTelemetryConsent({ ORLY_TELEMETRY: "anonymous" }, "off")).toBe("anonymous");
+    expect(resolveTelemetryConsent({ ORLY_TELEMETRY: "invalid" }, "anonymous")).toBe("off");
+    expect(resolveTelemetryConsent({}, "anonymous")).toBe("anonymous");
+    expect(resolveTelemetryConsent({})).toBe("off");
+  });
+
+  test("prompts_once_and_marks_aborted_prompt", async () => {
+    const root = temporaryRoot();
+    let prompts = 0;
+    const options = {
+      env: { [STATE_ENV]: root }, stdinIsTty: true, stdoutIsTty: true,
+      ask: () => { prompts += 1; return null; },
+    };
+    expect(await beginTelemetry(["doctor"], options)).toBeUndefined();
+    expect(await beginTelemetry(["doctor"], options)).toBeUndefined();
+    expect(prompts).toBe(1);
+    expect(await Bun.file(join(root, "orly/.telemetry-prompted")).exists()).toBe(true);
+    expect(await Bun.file(join(root, "orly/.orly.json")).json()).toEqual({ telemetry: "off" });
+  });
+
+  test("anonymous_opt_in_persists_identity_and_does_not_reprompt", async () => {
+    const root = temporaryRoot();
+    let prompts = 0;
+    const options = {
+      env: { [STATE_ENV]: root }, stdinIsTty: true, stdoutIsTty: true,
+      ask: () => { prompts += 1; return "2"; }, randomId: idSequence(40, 41, 42),
+    };
+    const first = await beginTelemetry(["doctor"], options);
+    const second = await beginTelemetry(["doctor"], options);
+
+    expect(prompts).toBe(1);
+    expect(first).toMatchObject({ command: "doctor", invocation: "direct", installationId: uuid(41) });
+    expect(second?.installationId).toBe(first?.installationId);
+    expect(await Bun.file(join(root, "orly/.orly.json")).json()).toEqual({ telemetry: "anonymous" });
+    expect(await Bun.file(join(root, "orly/installation-id")).text()).toBe(`${uuid(41)}\n`);
+  });
+
+  test("automation_never_prompts_for_telemetry", async () => {
+    const root = temporaryRoot();
+    let prompts = 0;
+    const ask = () => { prompts += 1; return "2"; };
+    await beginTelemetry(["gate"], { env: { [STATE_ENV]: root, ORLY_INVOCATION: "hook" }, stdinIsTty: true, stdoutIsTty: true, ask });
+    await beginTelemetry(["gate"], { env: { [STATE_ENV]: root, CI: "true" }, stdinIsTty: true, stdoutIsTty: true, ask });
+    await beginTelemetry(["gate"], { env: { [STATE_ENV]: root }, stdinIsTty: false, stdoutIsTty: false, ask });
+    await beginTelemetry(["skill-event", "orly-spec-new"], { env: { [STATE_ENV]: root, ORLY_INVOCATION: "skill" }, stdinIsTty: true, stdoutIsTty: true, ask });
+    expect(prompts).toBe(0);
+  });
+
+  test("consent_prompt_discloses_complete_collection_boundary", () => {
+    for (const phrase of [
+      "command, gate, and packaged Orly skill names", "failed gate criterion", "duration, Orly version", "installation IDs", "persists",
+      "source code, file contents, prompts", "file paths, working directory", "environment variables", "raw error messages",
+      "name, email, username, hostname", "Off", "default", "Anonymous",
+    ]) expect(TELEMETRY_PROMPT).toContain(phrase);
+  });
+});
+
+describe("telemetry events", () => {
+  test("appends_one_valid_event_per_command", async () => {
+    const root = temporaryRoot();
+    const session = await anonymousSession(root, idSequence(1, 2));
+    let launches = 0;
+    await recordTelemetry(session, observation(), { now: () => FIXED_TIME, randomId: () => uuid(3), launchSync: () => { launches += 1; } });
+    const events = await readTelemetrySpool(join(root, "orly"), FIXED_TIME);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ command: "gate", gate: "verify", outcome: "error", failed_criterion: "verify.unit" });
+    expect(launches).toBe(1);
+  });
+
+  test("anonymous_installation_identity_is_stable_and_random", async () => {
+    const root = temporaryRoot();
+    const first = await anonymousSession(root, idSequence(10, 11));
+    const second = await anonymousSession(root, idSequence(12, 13));
+    expect(first?.installationId).toBe(uuid(11));
+    expect(second?.installationId).toBe(first?.installationId);
+    expect(first?.installationId).not.toContain(process.env.USER ?? PRIVATE_SENTINEL);
+  });
+
+  test("event_schema_rejects_private_context", async () => {
+    const root = temporaryRoot();
+    const session = await beginTelemetry(["gate", PRIVATE_SENTINEL], {
+      env: { [STATE_ENV]: root, [ANONYMOUS_ENV]: "anonymous", PRIVATE_VALUE: PRIVATE_SENTINEL },
+      stdinIsTty: false, stdoutIsTty: false, randomId: idSequence(20, 21),
+    });
+    await recordTelemetry(session, observation(), { now: () => FIXED_TIME, randomId: () => uuid(22), launchSync: () => undefined });
+    const text = await Bun.file(join(root, "orly/analytics/orly-usage.jsonl")).text();
+    expect(text).not.toContain(PRIVATE_SENTINEL);
+    const value = JSON.parse(text);
+    expect(parseTelemetryEvent(JSON.stringify({ ...value, repository: PRIVATE_SENTINEL }))).toBeUndefined();
+  });
+
+  test("packaged_skill_uses_the_command_spool", async () => {
+    const root = temporaryRoot();
+    const session = await beginTelemetry(["skill-event", "orly-write-unit-test"], {
+      env: { [STATE_ENV]: root, [ANONYMOUS_ENV]: "anonymous", ORLY_INVOCATION: "skill" },
+      stdinIsTty: true, stdoutIsTty: true, randomId: idSequence(30, 31),
+    });
+    await recordTelemetry(session, { outcome: "success", durationMs: 1, version: "0.6.9" }, {
+      now: () => FIXED_TIME, randomId: () => uuid(32), launchSync: () => undefined,
+    });
+    const events = await readTelemetrySpool(join(root, "orly"), FIXED_TIME);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ command: "skill", skill: "orly-write-unit-test", invocation: "skill" });
+    expect(parseTelemetryEvent(JSON.stringify({ ...events[0], skill: "unknown-skill" }))).toBeUndefined();
+  });
+
+  test("spool_lock_drops_contention_without_losing_the_owner_write", async () => {
+    const root = join(temporaryRoot(), "orly");
+    let contenderResult: boolean | undefined;
+    const ownerResult = await withSpoolLock(root, async () => {
+      contenderResult = await withSpoolLock(root, async () => {
+        throw new Error("contending writer must not run");
+      });
+      await replaceTelemetrySpool(root, [event(450)], FIXED_TIME);
+    });
+
+    expect(ownerResult).toBe(true);
+    expect(contenderResult).toBe(false);
+    expect((await readTelemetrySpool(root, FIXED_TIME)).map((entry) => entry.event_id)).toEqual([uuid(450)]);
+  });
+});
+
+describe("telemetry synchronization", () => {
+  test("sync_is_consent_gated_and_schema_safe", async () => {
+    const root = temporaryRoot();
+    const stateRoot = join(root, "orly");
+    await replaceTelemetrySpool(stateRoot, [event(1)], FIXED_TIME);
+    const bodies: unknown[] = [];
+    const fetchImpl = captureFetch(bodies);
+    await syncTelemetry({ env: { [STATE_ENV]: root, ORLY_TELEMETRY_OFF: "1" }, now: () => FIXED_TIME, fetchImpl });
+    expect(bodies).toHaveLength(0);
+    await syncTelemetry({ env: { [STATE_ENV]: root, [ANONYMOUS_ENV]: "anonymous" }, now: () => FIXED_TIME, fetchImpl });
+    const sent = postHogBatch(bodies[0]);
+    expect(sent).toHaveLength(1);
+    const properties = postHogProperties(sent[0]);
+    expect(Object.keys(properties).sort()).toEqual([
+      "$insert_id", "arch", "command", "distinct_id", "duration_ms", "event_id", "installation_id", "invocation",
+      "orly_version", "os", "outcome", "schema_version", "session_id",
+    ]);
+  });
+
+  test("sync_spaces_attempts_and_bounds_batches", async () => {
+    const root = temporaryRoot();
+    const stateRoot = join(root, "orly");
+    await replaceTelemetrySpool(stateRoot, Array.from({ length: 101 }, (_, index) => event(index + 1)), FIXED_TIME);
+    const bodies: unknown[] = [];
+    const options = { env: { [STATE_ENV]: root, [ANONYMOUS_ENV]: "anonymous" }, now: () => FIXED_TIME, fetchImpl: captureFetch(bodies) };
+    await syncTelemetry(options);
+    await syncTelemetry(options);
+    expect(bodies).toHaveLength(1);
+    expect(postHogBatch(bodies[0])).toHaveLength(100);
+    expect((await readTelemetrySpool(stateRoot, FIXED_TIME)).map((entry) => entry.event_id)).toEqual([uuid(101)]);
+    expect(await Bun.file(join(stateRoot, "analytics/.last-sync-time")).text()).toBe(`${FIXED_TIME.toISOString()}\n`);
+  });
+
+  test("sync_retries_without_losing_or_renaming_events", async () => {
+    const root = temporaryRoot();
+    const stateRoot = join(root, "orly");
+    const original = [event(201), event(202)];
+    await replaceTelemetrySpool(stateRoot, original, FIXED_TIME);
+    const failedBodies: unknown[] = [];
+    const env = { [STATE_ENV]: root, [ANONYMOUS_ENV]: "anonymous" };
+    await syncTelemetry({ env, now: () => FIXED_TIME, fetchImpl: failingFetch(failedBodies) });
+    expect((await readTelemetrySpool(stateRoot, FIXED_TIME)).map((entry) => entry.event_id)).toEqual(original.map((entry) => entry.event_id));
+    const retryTime = new Date(FIXED_TIME.getTime() + FIVE_MINUTES_MILLISECONDS + 1);
+    const successBodies: unknown[] = [];
+    await syncTelemetry({ env, now: () => retryTime, fetchImpl: captureFetch(successBodies) });
+    expect(postHogIds(successBodies[0])).toEqual(postHogIds(failedBodies[0]));
+    expect(await readTelemetrySpool(stateRoot, retryTime)).toEqual([]);
+  });
+
+  test("sync_retains_events_when_fetch_rejects", async () => {
+    const root = temporaryRoot();
+    const stateRoot = join(root, "orly");
+    const original = [event(250)];
+    await replaceTelemetrySpool(stateRoot, original, FIXED_TIME);
+
+    await syncTelemetry({
+      env: { [STATE_ENV]: root, [ANONYMOUS_ENV]: "anonymous" },
+      now: () => FIXED_TIME,
+      fetchImpl: async () => { throw new Error("network unavailable"); },
+    });
+
+    expect((await readTelemetrySpool(stateRoot, FIXED_TIME)).map((entry) => entry.event_id)).toEqual(original.map((entry) => entry.event_id));
+  });
+
+  test("sync_compacts_and_bounds_local_spool", async () => {
+    const root = temporaryRoot();
+    const stateRoot = join(root, "orly");
+    const old = new Date(FIXED_TIME.getTime() - 8 * 24 * 60 * 60 * 1_000).toISOString();
+    const large = Array.from({ length: 20 }, (_, index) => ({ ...event(index + 300), orly_version: "x".repeat(600_000) }));
+    await replaceTelemetrySpool(stateRoot, [event(299, old), ...large], FIXED_TIME);
+    const path = join(stateRoot, "analytics/orly-usage.jsonl");
+    expect(statSync(path).size).toBeLessThanOrEqual(MAX_SPOOL_BYTES);
+    const events = await readTelemetrySpool(stateRoot, FIXED_TIME);
+    expect(events.some((entry) => entry.event_id === uuid(299))).toBe(false);
+    expect(events.at(-1)?.event_id).toBe(uuid(319));
+  });
+
+  test("sync_names_skill_events_separately", async () => {
+    const root = temporaryRoot();
+    const stateRoot = join(root, "orly");
+    await replaceTelemetrySpool(stateRoot, [{ ...event(400), command: "skill", skill: "orly-spec-new", invocation: "skill" }], FIXED_TIME);
+    const bodies: unknown[] = [];
+    await syncTelemetry({
+      env: { [STATE_ENV]: root, [ANONYMOUS_ENV]: "anonymous" }, now: () => FIXED_TIME, fetchImpl: captureFetch(bodies),
+    });
+    const sent = postHogBatch(bodies[0]);
+    expect(isRecord(sent[0]) ? sent[0].event : undefined).toBe("orly_skill_run");
+    expect(postHogProperties(sent[0]).skill).toBe("orly-spec-new");
+  });
+});
+
+function observation() {
+  return { gate: "verify", outcome: "error" as const, failedCriterion: "verify.unit", durationMs: 42, version: "0.6.9" };
+}
+
+async function anonymousSession(root: string, randomId: () => string) {
+  return beginTelemetry(["gate", "verify"], {
+    env: { [STATE_ENV]: root, [ANONYMOUS_ENV]: "anonymous" }, stdinIsTty: false, stdoutIsTty: false, randomId,
+  });
+}
+
+function event(index: number, timestamp = FIXED_TIME.toISOString()): TelemetryEvent {
+  return {
+    schema_version: 1, event_id: uuid(index), timestamp, command: "gate", outcome: "success", duration_ms: index,
+    orly_version: "0.6.9", os: "darwin", arch: "arm64", invocation: "direct", session_id: uuid(9_000 + index), installation_id: uuid(8_000),
+  };
+}
+
+function temporaryRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), "orly-telemetry-test-"));
+  temporaryRoots.push(root);
+  return root;
+}
+
+function idSequence(...values: number[]): () => string {
+  let index = 0;
+  return () => uuid(values[index++] ?? 999_999);
+}
+
+function uuid(value: number): string {
+  return `00000000-0000-4000-8000-${value.toString(16).padStart(12, "0")}`;
+}
+
+function captureFetch(bodies: unknown[]) {
+  return async (_input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    bodies.push(JSON.parse(String(init?.body)));
+    return new Response("ok", { status: 200 });
+  };
+}
+
+function failingFetch(bodies: unknown[]) {
+  return async (_input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    bodies.push(JSON.parse(String(init?.body)));
+    return new Response("unavailable", { status: 503 });
+  };
+}
+
+function postHogBatch(body: unknown): unknown[] {
+  return isRecord(body) && Array.isArray(body.batch) ? body.batch : [];
+}
+
+function postHogProperties(value: unknown): Record<string, unknown> {
+  return isRecord(value) && isRecord(value.properties) ? value.properties : {};
+}
+
+function postHogIds(body: unknown): unknown[] {
+  return postHogBatch(body).map((entry) => postHogProperties(entry).event_id);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}