@indigoai-us/hq-cloud 6.14.0 → 6.14.2

package/src/s3.test.ts

@@ -93,6 +93,7 @@ import {
   decodeSymlinkMetadataValue,
   FILE_MTIME_META_KEY,
   FILE_BTIME_META_KEY,
+  validateVaultUploadKey,
 } from "./s3.js";
 import {
   setObjectIOFactory,
@@ -1384,3 +1385,89 @@ describe("downloadFile", () => {
     expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
   });
 });
+
+describe("validateVaultUploadKey — direct-S3 key poisoning guard (incident 2026-07-11)", () => {
+  // The direct-S3 STS transport bypasses hq-pro's server-side validateObjectKey
+  // (files-acl.ts), so uploadFile/uploadSymlink must enforce the SAME rules
+  // before the PUT. Incident: a stale doubled local tree
+  // (companies/indigo/companies/indigo/…) pushed 25 literal `companies/…` keys
+  // into a company vault; the presign download API then rejected every one
+  // (INVALID_KEY_COMPANIES_SCOPED), erroring the whole company sync fleet-wide.
+  let tmpFile: string;
+
+  function makePersonalCtx(): EntityContext {
+    return { ...makeCtx(), uid: "prs_TEST" };
+  }
+
+  beforeEach(() => {
+    sentCommands.length = 0;
+    tmpFile = path.join(
+      os.tmpdir(),
+      `s3-keyguard-test-${Date.now()}-${Math.random()}.md`,
+    );
+    fs.writeFileSync(tmpFile, "hello");
+  });
+
+  afterEach(() => {
+    try {
+      fs.unlinkSync(tmpFile);
+    } catch {
+      // already gone
+    }
+  });
+
+  it("validateVaultUploadKey rejects companies/-prefixed keys in company scope with the server's error code", () => {
+    expect(() =>
+      validateVaultUploadKey("companies/indigo/knowledge/x.md", "company"),
+    ).toThrowError(
+      expect.objectContaining({ code: "INVALID_KEY_COMPANIES_SCOPED" }),
+    );
+  });
+
+  it("validateVaultUploadKey allows companies/-prefixed keys in personal scope (local non-cloud companies)", () => {
+    expect(() =>
+      validateVaultUploadKey("companies/indigo/knowledge/x.md", "personal"),
+    ).not.toThrow();
+  });
+
+  it.each([
+    ["", "INVALID_KEY_EMPTY"],
+    ["/leading.md", "INVALID_KEY_LEADING_SLASH"],
+    ["folder/", "INVALID_KEY_TRAILING_SLASH"],
+    ["a//b.md", "INVALID_KEY_DOUBLE_SLASH"],
+    ["a/../b.md", "INVALID_KEY_DOT_COMPONENT"],
+    ["a/./b.md", "INVALID_KEY_DOT_COMPONENT"],
+    ["bad\x00key.md", "INVALID_KEY_CONTROL_CHARS"],
+  ])(
+    "validateVaultUploadKey mirrors the server rule set: %j → %s",
+    (key, code) => {
+      expect(() => validateVaultUploadKey(key, "company")).toThrowError(
+        expect.objectContaining({ code }),
+      );
+      expect(() => validateVaultUploadKey(key, "personal")).toThrowError(
+        expect.objectContaining({ code }),
+      );
+    },
+  );
+
+  it("uploadFile refuses to PUT a companies/-prefixed key into a company (cmp_) vault — no S3 command is sent", async () => {
+    await expect(
+      uploadFile(makeCtx(), tmpFile, "companies/indigo/knowledge/x.md"),
+    ).rejects.toMatchObject({ code: "INVALID_KEY_COMPANIES_SCOPED" });
+    expect(sentCommands.length).toBe(0);
+  });
+
+  it("uploadSymlink refuses to PUT a companies/-prefixed key into a company (cmp_) vault — no S3 command is sent", async () => {
+    await expect(
+      uploadSymlink(makeCtx(), "../target.md", "companies/indigo/link.md"),
+    ).rejects.toMatchObject({ code: "INVALID_KEY_COMPANIES_SCOPED" });
+    expect(sentCommands.length).toBe(0);
+  });
+
+  it("uploadFile still allows companies/-prefixed keys for a personal (prs_) vault", async () => {
+    await expect(
+      uploadFile(makePersonalCtx(), tmpFile, "companies/indigo/knowledge/x.md"),
+    ).resolves.toBeDefined();
+    expect(sentCommands.length).toBeGreaterThan(0);
+  });
+});

package/src/s3.ts

@@ -541,6 +541,90 @@ export function toPosixKey(key: string): string {
   return key.split("\\").join("/");
 }
 
+/**
+ * Client-side mirror of hq-pro's server validator
+ * (`vault-service/handlers/files-acl.ts validateObjectKey`). The direct-S3
+ * STS transport bypasses server key validation entirely — the upload
+ * primitives (uploadFile / uploadSymlink) are the only shared choke point —
+ * so we enforce the SAME rules here BEFORE the PUT. Incident 2026-07-11: a
+ * client with a stale doubled local tree (companies/{slug}/companies/{slug}/…)
+ * pushed literal `companies/…` keys into a company-scoped vault bucket via
+ * direct S3; agent boxes could LIST them but the presign download API
+ * rejected every one (INVALID_KEY_COMPANIES_SCOPED), erroring the whole
+ * company sync fleet-wide. A poisoned key must fail loudly at the writer,
+ * not at every reader.
+ *
+ * `scope` selects the companies/-prefix rule: company vault buckets are
+ * already company-scoped so a `companies/…` key is always wrong there;
+ * personal vaults legitimately carry `companies/{slug}/…` keys for local
+ * (non-cloud) companies. Callers derive scope from the EntityContext uid
+ * (`cmp_*` → "company", otherwise "personal").
+ *
+ * Errors carry the same `code` values the server throws so telemetry and
+ * operator messaging line up across client and server.
+ */
+// Matching control chars is the whole point — block NUL/0x00–0x1F/0x7F in keys
+// (they can smuggle past path checks or corrupt HTTP headers on the signed URL).
+// eslint-disable-next-line no-control-regex
+const KEY_CONTROL_CHARS = /[\x00-\x1F\x7F]/;
+
+export function validateVaultUploadKey(
+  key: string,
+  scope: "company" | "personal",
+): void {
+  const fail = (message: string, code: string): never => {
+    throw Object.assign(new Error(message), { code });
+  };
+  if (key.length === 0) {
+    fail("Invalid key: must not be empty", "INVALID_KEY_EMPTY");
+  }
+  if (key.startsWith("/")) {
+    fail("Invalid key: leading '/' not allowed", "INVALID_KEY_LEADING_SLASH");
+  }
+  if (key.endsWith("/")) {
+    fail(
+      "Invalid key: trailing '/' (folder marker, not an object)",
+      "INVALID_KEY_TRAILING_SLASH",
+    );
+  }
+  if (scope === "company" && key.startsWith("companies/")) {
+    fail(
+      "Invalid key: vault keys are bucket-relative and the vault is already " +
+        "company-scoped — do not prefix with 'companies/<slug>/'. This " +
+        "usually means a stale doubled local tree " +
+        "(companies/<slug>/companies/<slug>/…); remove the inner copy.",
+      "INVALID_KEY_COMPANIES_SCOPED",
+    );
+  }
+  if (KEY_CONTROL_CHARS.test(key)) {
+    fail("Invalid key: contains control characters", "INVALID_KEY_CONTROL_CHARS");
+  }
+  if (key.includes("\\")) {
+    // Unreachable after toPosixKey normalization at the upload boundary, but
+    // kept so the validator mirrors the server rule set 1:1 for other callers.
+    fail(
+      "Invalid key: backslash separators are not allowed — vault keys are POSIX ('/')",
+      "INVALID_KEY_BACKSLASH",
+    );
+  }
+  if (key.includes("//")) {
+    fail("Invalid key: consecutive slashes not allowed", "INVALID_KEY_DOUBLE_SLASH");
+  }
+  for (const segment of key.split("/")) {
+    if (segment === "." || segment === "..") {
+      fail(
+        "Invalid key: '.' and '..' path components are not allowed",
+        "INVALID_KEY_DOT_COMPONENT",
+      );
+    }
+  }
+}
+
+/** Scope for {@link validateVaultUploadKey}, derived from the entity uid. */
+function uploadScopeFor(ctx: EntityContext): "company" | "personal" {
+  return ctx.uid.startsWith("cmp_") ? "company" : "personal";
+}
+
 export async function uploadFile(
   ctx: EntityContext,
   localPath: string,
@@ -548,8 +632,12 @@ export async function uploadFile(
   author?: UploadAuthor,
   precondition?: PutPrecondition,
 ): Promise<{ etag: string }> {
-  // Boundary guardrail: never store a non-POSIX key (see toPosixKey).
+  // Boundary guardrail: never store a non-POSIX key (see toPosixKey), and
+  // never store a key the server-side validator would reject (see
+  // validateVaultUploadKey — the direct-S3 STS transport bypasses server
+  // validation, so this is the last line of defense against key poisoning).
   key = toPosixKey(key);
+  validateVaultUploadKey(key, uploadScopeFor(ctx));
   const io = resolveObjectIO(ctx);
   const body = fs.readFileSync(localPath);
 
@@ -616,8 +704,11 @@ export async function uploadSymlink(
   author?: UploadAuthor,
   precondition?: PutPrecondition,
 ): Promise<{ etag: string }> {
-  // Boundary guardrail: never store a non-POSIX key (see toPosixKey).
+  // Boundary guardrail: never store a non-POSIX key (see toPosixKey), and
+  // never store a key the server-side validator would reject (see
+  // validateVaultUploadKey).
   key = toPosixKey(key);
+  validateVaultUploadKey(key, uploadScopeFor(ctx));
   const io = resolveObjectIO(ctx);
   const symlinkBody = encodeSymlinkBody(target);
 

package/src/scope-shrink.test.ts

@@ -240,6 +240,38 @@ describe("buildScopeShrinkPlan", () => {
     expect(plan.orphans).toEqual([]);
   });
 
+  // US-006: a session transcript authored + pushed locally (direction: "up")
+  // under the push-only `sessions/{personUid}/` prefix must NEVER be orphaned by
+  // a scope shrink, even though `sessions/` sits outside the effective pull
+  // scope (it is subtracted from every pull scope as an excludePrefix). This is
+  // the authorship arm of the push-only contract: sessions are pushed, then
+  // never pulled, and the direction:"up" exemption keeps the author's own
+  // transcript from being pruned. Regression guard for AC4/AC6.
+  it("never orphans a locally-authored session (direction: 'up') when sessions is outside pull scope (US-006)", () => {
+    const journal: SyncJournal = {
+      ...emptyJournal(),
+      files: {
+        "sessions/prs_1/2026-07-11T10-00-00.json": {
+          hash: "h",
+          size: 1,
+          syncedAt: "2026-07-11T00:00:00.000Z",
+          direction: "up",
+        },
+      },
+    };
+    const plan = buildScopeShrinkPlan({
+      journal,
+      hqRoot,
+      // Last pull saw everything ([""] = full scope); the current pull scope
+      // covers knowledge but NOT the push-only sessions prefix — exactly the
+      // shape the sessions exclusion produces on the download side.
+      lastPrefixSet: [""],
+      currentPrefixSet: ["knowledge/"],
+    });
+    expect(plan.orphans).toEqual([]);
+    expect(plan.scopeChangeDetected).toBe(false);
+  });
+
   // ── Authorship guard ──────────────────────────────────────────────────────
   // Sync mode decides whether you mirror OTHER people's files; it must never
   // orphan content the caller authored. Owners hold their whole vault by

package/src/scope-shrink.ts

@@ -18,6 +18,18 @@
  * tombstone write — that lives in `journal.ts`. It DOES touch disk for the
  * orphan classification (hash + stat) because cleanliness is a function of
  * the file's current on-disk state vs the journal.
+ *
+ * PUSH-ONLY PREFIXES ARE NEVER PRUNED HERE (US-006). Session transcripts under
+ * `sessions/{personUid}/...` are push-only: pushed into the vault, then
+ * subtracted from every pull scope (incl. `all`/owner) via
+ * `resolvePullScope().excludePrefixes`. That exclude set is applied ONLY to the
+ * download filter (`computePullPlan`) and is DELIBERATELY NOT passed into this
+ * module's `currentPrefixSet`. So a session file that was authored locally rides
+ * the `direction:"up"` skip below, and one materialized on demand (`hq files
+ * get`) rides the pin union already folded into the caller's inclusion
+ * `prefixSet` — either way it is never pulled AND never orphaned. Feeding the
+ * exclude set into `currentPrefixSet` would prune exactly those files; callers
+ * must not.
  */
 
 import * as fs from "fs";

package/src/skill-telemetry.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, vi } from "vitest";
 import { promises as fs } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { createHash } from "node:crypto";
 import {
   extractSkillEvents,
   extractCodexSkillEvents,
@@ -9,6 +10,7 @@ import {
   codexRowTurnId,
   parseCodexSessionMeta,
   collectAndSendSkillTelemetry,
+  computeSkillVersion,
   readFileRegion,
 } from "./skill-telemetry.js";
 import type { SkillInvocationBatch } from "./vault-client.js";
@@ -226,6 +228,58 @@ describe("extractCodexSkillToolEvents (Codex model-driven SKILL.md reads)", () =
     expect(ev.source).toBe("model");
   });
 
+  it("reconstructs <slug>:<name> when reading a company skill's real path", () => {
+    // Codex loads a company skill by reading companies/<slug>/skills/<name>/
+    // SKILL.md; the slug must be recovered so the run attributes to the company
+    // rather than being dropped to a bare, unattributed name.
+    const ev = extractCodexSkillToolEvents(
+      execEnd("sed -n '1,240p' companies/indigo/skills/signals/SKILL.md"),
+      ctx,
+    )[0];
+    expect(ev.skill).toBe("indigo:signals");
+    expect(ev.source).toBe("model");
+    // The dedup/idempotency uuid keys off the reconstructed token.
+    expect(ev.uuid).toBe("codex:skill:sess-x:turn-A:indigo:signals");
+  });
+
+  it("reconstructs the slug for any company and absolute path", () => {
+    expect(
+      extractCodexSkillToolEvents(
+        execEnd("cat /home/ec2-user/hq/companies/beta/skills/support/SKILL.md"),
+        ctx,
+      )[0].skill,
+    ).toBe("beta:support");
+    // Hyphenated slug + hyphenated skill name both survive.
+    expect(
+      extractCodexSkillToolEvents(
+        execEnd("rg -n x companies/indigo-auto/skills/call-prep-brief/SKILL.md"),
+        ctx,
+      )[0].skill,
+    ).toBe("indigo-auto:call-prep-brief");
+  });
+
+  it("leaves an already-namespaced symlink read untouched (no double prefix)", () => {
+    // Reading via the .claude/skills/<slug>:<name>/ symlink already carries the
+    // prefix in the captured directory — it must NOT get a second one.
+    expect(
+      extractCodexSkillToolEvents(
+        execEnd("cat .claude/skills/indigo:signals/SKILL.md"),
+        ctx,
+      )[0].skill,
+    ).toBe("indigo:signals");
+  });
+
+  it("does not fabricate a company prefix for a non-company skill", () => {
+    // A core skill read from its bare directory stays bare — the reconstruction
+    // only triggers on the companies/<slug>/skills/ shape.
+    expect(
+      extractCodexSkillToolEvents(
+        execEnd("cat .claude/skills/deploy/SKILL.md"),
+        ctx,
+      )[0].skill,
+    ).toBe("deploy");
+  });
+
   it("matches normal Codex skill paths without backtracking ambiguity", () => {
     expect(
       extractCodexSkillToolEvents(
@@ -1102,10 +1156,13 @@ describe("collectAndSendSkillTelemetry — companyUid attribution", () => {
     await fs.writeFile(
       path.join(dir, "s.jsonl"),
       [
-        // cwd inside the company repo → attributed.
+        // Core skill, cwd inside the company repo → attributed by cwd.
         row({ type: "user", sessionId: "s1", timestamp: "2026-06-10T10:00:00Z", cwd: inRepo, uuid: "u1", message: { role: "user", content: "<command-name>/deploy</command-name>" } }),
-        // cwd at hqRoot (passes scope) but maps to no repo → unattributed.
+        // Company skill `indigo:hello-world` run at hqRoot (maps to no repo) →
+        // attributed by SKILL NAMESPACE to the indigo company, regardless of cwd.
         row({ type: "assistant", sessionId: "s1", timestamp: "2026-06-10T10:01:00Z", cwd: atRoot, message: { role: "assistant", content: [{ type: "tool_use", id: "t1", name: "Skill", input: { skill: "indigo:hello-world" } }] } }),
+        // Core skill at hqRoot (no company repo, no namespace) → unattributed.
+        row({ type: "user", sessionId: "s1", timestamp: "2026-06-10T10:02:00Z", cwd: atRoot, uuid: "u3", message: { role: "user", content: "<command-name>/handoff</command-name>" } }),
       ].join("\n") + "\n",
       "utf-8",
     );
@@ -1121,11 +1178,15 @@ describe("collectAndSendSkillTelemetry — companyUid attribution", () => {
       cursorPath: path.join(tmp, "cursor.json"),
     });
 
-    expect(result.eventsSent).toBe(2);
+    expect(result.eventsSent).toBe(3);
     const events = captured.flatMap((b) => b.events);
     const bySkill = new Map(events.map((e) => [e.skill, e]));
+    // Core skill attributed by its cwd (inside the company repo).
     expect(bySkill.get("deploy")!.companyUid).toBe(COMPANY_UID);
-    expect("companyUid" in bySkill.get("indigo:hello-world")!).toBe(false);
+    // Company skill attributed by its namespace, even though cwd maps to no repo.
+    expect(bySkill.get("indigo:hello-world")!.companyUid).toBe(COMPANY_UID);
+    // Core skill at hqRoot with no owning repo → stays unattributed.
+    expect("companyUid" in bySkill.get("handoff")!).toBe(false);
     // Never the reserved sentinel.
     for (const e of events) expect(e.companyUid).not.toBe("unattributed");
 
@@ -1275,3 +1336,185 @@ describe("readFileRegion — HQ-SYNC-WEB-15 (SIGABRT on >2GiB single read)", ()
     expect(got).toBe(30);
   });
 });
+
+describe("computeSkillVersion (US-015)", () => {
+  function sha256(bytes: string): string {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+  }
+
+  it("hashes .claude/skills/<skill>/SKILL.md to a sha256:<hex> marker", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "skill-ver-"));
+    const body = "---\nname: deploy\n---\nDeploy things.\n";
+    const dir = path.join(tmp, ".claude", "skills", "deploy");
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, "SKILL.md"), body, "utf-8");
+
+    expect(await computeSkillVersion(tmp, "deploy")).toBe(sha256(body));
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  it("resolves a namespaced skill by its full invocation name (colon in dir name)", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "skill-ver-"));
+    const body = "hello world skill\n";
+    const dir = path.join(tmp, ".claude", "skills", "indigo:hello-world");
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, "SKILL.md"), body, "utf-8");
+
+    expect(await computeSkillVersion(tmp, "indigo:hello-world")).toBe(sha256(body));
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  it("falls back to .agents/skills/ (Codex bridge layout)", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "skill-ver-"));
+    const body = "codex-bridged skill\n";
+    const dir = path.join(tmp, ".agents", "skills", "learn");
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, "SKILL.md"), body, "utf-8");
+
+    expect(await computeSkillVersion(tmp, "learn")).toBe(sha256(body));
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  it("returns undefined for a missing hqRoot, a missing file, or a traversal attempt", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "skill-ver-"));
+    expect(await computeSkillVersion(undefined, "deploy")).toBeUndefined();
+    expect(await computeSkillVersion(tmp, "does-not-exist")).toBeUndefined();
+    // Path-traversal / separator-bearing names never map to a SKILL.md here.
+    expect(await computeSkillVersion(tmp, "../../etc/passwd")).toBeUndefined();
+    expect(await computeSkillVersion(tmp, "a/b")).toBeUndefined();
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+});
+
+describe("collectAndSendSkillTelemetry — skillVersion emission (US-015)", () => {
+  function stubClient(captured: SkillInvocationBatch[]) {
+    return {
+      async getTelemetryOptIn() {
+        return { enabled: true, updatedAt: null };
+      },
+      async postSkillInvocations(batch: SkillInvocationBatch) {
+        captured.push(batch);
+        return { ok: true, written: batch.events.length, skipped: [] };
+      },
+    };
+  }
+  function row(obj: Record<string, unknown>): string {
+    return JSON.stringify(obj);
+  }
+
+  it("stamps the SKILL.md content hash onto the shipped event", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "skill-ver-emit-"));
+    // hqRoot IS the session cwd, so the invocation passes the scope filter and
+    // the resolver can find the skill under hqRoot/.claude/skills.
+    const hqRoot = path.join(tmp, "hq");
+    const skillBody = "---\nname: deploy\n---\nDeploy.\n";
+    const skillDir = path.join(hqRoot, ".claude", "skills", "deploy");
+    await fs.mkdir(skillDir, { recursive: true });
+    await fs.writeFile(path.join(skillDir, "SKILL.md"), skillBody, "utf-8");
+
+    const projects = path.join(tmp, "projects");
+    const dir = path.join(projects, "-hq");
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(
+      path.join(dir, "s.jsonl"),
+      row({
+        type: "user",
+        sessionId: "s1",
+        timestamp: "2026-07-09T09:00:00Z",
+        cwd: hqRoot,
+        uuid: "u1",
+        message: { role: "user", content: "<command-name>/deploy</command-name>" },
+      }) + "\n",
+      "utf-8",
+    );
+
+    const captured: SkillInvocationBatch[] = [];
+    const result = await collectAndSendSkillTelemetry({
+      client: stubClient(captured),
+      machineId: "m",
+      installerVersion: "t",
+      hqRoot,
+      claudeProjectsRoot: projects,
+      codexSessionsRoot: path.join(tmp, "codex"),
+      cursorPath: path.join(tmp, "cursor.json"),
+    });
+
+    expect(result.eventsSent).toBe(1);
+    const ev = captured[0].events[0];
+    expect(ev.skill).toBe("deploy");
+    expect(ev.skillVersion).toBe(
+      `sha256:${createHash("sha256").update(skillBody).digest("hex")}`,
+    );
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  it("emits the injected resolver's marker (wiring is decoupled from disk)", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "skill-ver-inj-"));
+    const projects = path.join(tmp, "projects");
+    const dir = path.join(projects, "-p");
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(
+      path.join(dir, "s.jsonl"),
+      row({
+        type: "assistant",
+        sessionId: "s2",
+        timestamp: "2026-07-09T10:00:00Z",
+        cwd: "/x",
+        message: {
+          role: "assistant",
+          content: [{ type: "tool_use", id: "t1", name: "Skill", input: { skill: "code-review" } }],
+        },
+      }) + "\n",
+      "utf-8",
+    );
+
+    const captured: SkillInvocationBatch[] = [];
+    const result = await collectAndSendSkillTelemetry({
+      client: stubClient(captured),
+      machineId: "m",
+      installerVersion: "t",
+      claudeProjectsRoot: projects,
+      codexSessionsRoot: path.join(tmp, "codex"),
+      cursorPath: path.join(tmp, "cursor.json"),
+      resolveSkillVersion: (skill) => `sha256:stub-for-${skill}`,
+    });
+
+    expect(result.eventsSent).toBe(1);
+    expect(captured[0].events[0].skillVersion).toBe("sha256:stub-for-code-review");
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  it("omits skillVersion when the SKILL.md can't be resolved (additive/back-compat)", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "skill-ver-none-"));
+    const projects = path.join(tmp, "projects");
+    const dir = path.join(projects, "-p");
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(
+      path.join(dir, "s.jsonl"),
+      row({
+        type: "user",
+        sessionId: "s3",
+        timestamp: "2026-07-09T11:00:00Z",
+        cwd: "/x",
+        uuid: "u3",
+        message: { role: "user", content: "<command-name>/unknown-skill</command-name>" },
+      }) + "\n",
+      "utf-8",
+    );
+
+    // No hqRoot → the default resolver can't locate any SKILL.md → field omitted.
+    const captured: SkillInvocationBatch[] = [];
+    const result = await collectAndSendSkillTelemetry({
+      client: stubClient(captured),
+      machineId: "m",
+      installerVersion: "t",
+      claudeProjectsRoot: projects,
+      codexSessionsRoot: path.join(tmp, "codex"),
+      cursorPath: path.join(tmp, "cursor.json"),
+    });
+
+    expect(result.eventsSent).toBe(1);
+    expect("skillVersion" in captured[0].events[0]).toBe(false);
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+});