@indigoai-us/hq-cloud 6.14.23 → 6.14.25

package/src/s3.ts

@@ -317,7 +317,13 @@ function removeTempPath(tempPath: string): void {
   try {
     fs.unlinkSync(tempPath);
   } catch {
-    // Best-effort cleanup; do not mask the transfer/materialization error.
+    // A win32 directory-type symlink is a directory reparse point and
+    // refuses unlink (EPERM); rmdir is the correct removal call for it.
+    try {
+      fs.rmdirSync(tempPath);
+    } catch {
+      // Best-effort cleanup; do not mask the transfer/materialization error.
+    }
   }
 }
 
@@ -368,6 +374,69 @@ export function createStagedSymlink(
   ops.symlink(absTarget, linkPath, "junction");
 }
 
+/**
+ * downloadFile's `options.win32` seam is the authority for symlink-flavor
+ * decisions (it is what makes Windows semantics testable on POSIX CI), so the
+ * staged-link helper must see the SAME platform the idempotence fast path
+ * reasoned about rather than the raw `process.platform`. createStagedSymlink
+ * only ever asks "is this win32?", so "linux" is a faithful stand-in for
+ * "not Windows" on the false branch.
+ */
+function stagedSymlinkOpsFor(win32: boolean): CreateStagedSymlinkOps {
+  return {
+    ...DEFAULT_CREATE_STAGED_SYMLINK_OPS,
+    platform: win32 ? "win32" : "linux",
+  };
+}
+
+/**
+ * Would createStagedSymlink() materialize `target` as a DIRECTORY-flavored
+ * link (a junction) rather than a file symlink? Mirrors that helper's rule
+ * exactly — only a target confirmed to be a non-directory earns a file
+ * symlink; directories and unresolvable targets become junctions, which need
+ * no Windows privilege. Keeping the two in lockstep is what lets the
+ * idempotence fast path below decide whether an existing link is already the
+ * link we would mint today.
+ */
+function win32StagedLinkIsDirectoryFlavored(
+  target: string,
+  linkPath: string,
+  ops: CreateStagedSymlinkOps = DEFAULT_CREATE_STAGED_SYMLINK_OPS,
+): boolean {
+  const absTarget = path.isAbsolute(target)
+    ? target
+    : path.resolve(path.dirname(linkPath), target);
+  return ops.statIsDirectory(absTarget) !== false;
+}
+
+/**
+ * Compare an on-disk readlink() result against an incoming wire target.
+ *
+ * POSIX compares exactly: we write the wire target verbatim, so readlink()
+ * returns it byte-for-byte, and a backslash is an ordinary filename character
+ * there. On win32 neither property holds — createStagedSymlink() materializes
+ * directory overlays as JUNCTIONS, which require an ABSOLUTE substitute path,
+ * and Node rewrites '/' → '\\' at symlink() time. A raw string compare would
+ * therefore never match on Windows and the fast path would never fire for the
+ * .claude/skills link farm (the exact perpetual-churn bug this guards). So
+ * win32 equality resolves BOTH sides against the link's parent directory and
+ * compares separator-insensitively, which normalizes the relative wire target
+ * and the absolute junction target onto the same footing.
+ */
+function symlinkTargetsEqual(
+  existing: string,
+  incoming: string,
+  linkPath: string,
+  win32: boolean,
+): boolean {
+  if (!win32) return existing === incoming;
+  const normalize = (value: string): string =>
+    path
+      .resolve(path.dirname(linkPath), value.replace(/\\/g, "/"))
+      .replace(/\\/g, "/");
+  return normalize(existing) === normalize(incoming);
+}
+
 export interface ReplaceStagedPathOps {
   lstat(path: string): fs.Stats;
   rename(from: string, to: string): void;
@@ -377,7 +446,19 @@ export interface ReplaceStagedPathOps {
 const DEFAULT_REPLACE_STAGED_PATH_OPS: ReplaceStagedPathOps = {
   lstat: (p) => fs.lstatSync(p),
   rename: (from, to) => fs.renameSync(from, to),
-  remove: (p) => fs.unlinkSync(p),
+  remove: (p) => {
+    try {
+      fs.unlinkSync(p);
+    } catch (err) {
+      // A win32 directory-type symlink or junction is a directory reparse
+      // point; some runtimes refuse unlink (EPERM/EISDIR) and need rmdir —
+      // same fallback as removeTempPath. Anything else stays loud so
+      // replaceStagedPath can roll back.
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code !== "EPERM" && code !== "EISDIR") throw err;
+      fs.rmdirSync(p);
+    }
+  },
 };
 
 function replacementBackupPath(localPath: string): string {
@@ -1060,7 +1141,14 @@ export async function downloadFile(
   ctx: EntityContext,
   key: string,
   localPath: string,
-  options: { beforeReplace?: () => void } = {},
+  options: {
+    beforeReplace?: () => void;
+    /**
+     * Platform override so win32 symlink semantics are directly testable
+     * on any host (same convention as local-path-codec.ts).
+     */
+    win32?: boolean;
+  } = {},
 ): Promise<{
   metadata?: Record<string, string>;
   contentHash?: string;
@@ -1151,9 +1239,65 @@ export async function downloadFile(
       );
     }
 
+    // Idempotence fast path: the .claude/skills link farm makes symlink
+    // records the most re-pulled object class, and a pull that changes
+    // nothing must not touch disk at all (pre-fix, an already-correct
+    // Windows dir link still went through temp+rename, EPERM'd every
+    // pass, never journaled, and re-downloaded forever). On POSIX a
+    // target-string match is sufficient (lstat + readlink — never stat:
+    // dangling links are legitimate). On win32 a matching target string is
+    // NOT sufficient — links are flavored, and a file-type link at a
+    // directory target (minted by an older client, or while the target was
+    // absent) is broken despite the matching string. There the fast path
+    // additionally requires stat-follow to confirm the link FUNCTIONS as
+    // the type win32SymlinkType() would mint now; anything unconfirmable
+    // (including a dangling link, whose flavor cannot be probed) falls
+    // through to replacement, which is cheap and journals correctly.
+    const win32 = options.win32 ?? process.platform === "win32";
+    let existingLink: fs.Stats | null = null;
+    try {
+      existingLink = fs.lstatSync(localPath);
+    } catch {
+      // Absent (or unreadable) destination: no fast path; the normal
+      // materialization below surfaces real filesystem faults loudly.
+    }
+    if (existingLink?.isSymbolicLink()) {
+      let existingTarget: string | null = null;
+      try {
+        existingTarget = fs.readlinkSync(localPath);
+      } catch {
+        // Link raced away between lstat and readlink; replace it below.
+      }
+      if (
+        existingTarget !== null &&
+        symlinkTargetsEqual(existingTarget, symlinkTarget, localPath, win32)
+      ) {
+        if (!win32) return { metadata };
+        const desiredIsDirectory = win32StagedLinkIsDirectoryFlavored(
+          symlinkTarget,
+          localPath,
+        );
+        let followed: fs.Stats | null = null;
+        try {
+          followed = fs.statSync(localPath);
+        } catch {
+          // Unresolvable via this link (dangling, or a wrong-flavor link
+          // that Windows refuses to traverse): recreate below.
+        }
+        if (followed !== null && followed.isDirectory() === desiredIsDirectory) {
+          return { metadata };
+        }
+      }
+    }
+
     const tempPath = downloadTempPath(localPath);
     try {
-      createStagedSymlink(symlinkTarget, tempPath);
+      // Creation goes through createStagedSymlink (#219): on win32 a directory
+      // overlay becomes an unprivileged JUNCTION rather than a 'dir' NTFS
+      // symlink, which is what stops the EPERM that pushed the one-shot runner
+      // to PARTIAL_SYNC_EXIT. The staged link lands beside `localPath`, so its
+      // flavor decision resolves the target identically to the fast path above.
+      createStagedSymlink(symlinkTarget, tempPath, stagedSymlinkOpsFor(win32));
       options.beforeReplace?.();
       replaceStagedPath(tempPath, localPath);
     } catch (err) {

package/src/skill-telemetry.test.ts

@@ -13,6 +13,7 @@ import {
   computeSkillVersion,
   readFileRegion,
 } from "./skill-telemetry.js";
+import { encodeLocalVaultSegment } from "./local-path-codec.js";
 import type { SkillInvocationBatch } from "./vault-client.js";
 
 describe("extractSkillEvents", () => {
@@ -1364,6 +1365,24 @@ describe("computeSkillVersion (US-015)", () => {
     await fs.rm(tmp, { recursive: true, force: true });
   });
 
+  it("resolves an ALREADY-ENCODED local segment without double-encoding (win32 Codex path capture)", async () => {
+    // Codex telemetry extraction captures the on-disk wrapper name from a
+    // win32 path (`indigo%3Ahello-world`); encoding that again would look
+    // under `indigo%253A...` and miss. Normalization decodes to canonical
+    // first, then re-encodes for THIS host.
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "skill-ver-"));
+    const body = "encoded-name skill";
+    const hostDirName = encodeLocalVaultSegment("indigo:hello-world");
+    const dir = path.join(tmp, ".claude", "skills", hostDirName);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, "SKILL.md"), body, "utf-8");
+
+    expect(await computeSkillVersion(tmp, "indigo%3Ahello-world")).toBe(sha256(body));
+    // A decoded separator can never smuggle past the traversal guard.
+    expect(await computeSkillVersion(tmp, "a%2Fb")).toBeUndefined();
+    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";

package/src/skill-telemetry.ts

@@ -66,6 +66,10 @@ import {
   resolveCompanyForSkill,
   type RepoCompanyMap,
 } from "./company-resolver.js";
+import {
+  canonicalVaultSegmentSpelling,
+  encodeLocalVaultSegment,
+} from "./local-path-codec.js";
 import type {
   SkillInvocationBatch,
   SkillInvocationIngestResult,
@@ -621,10 +625,35 @@ export async function computeSkillVersion(
   if (skill.includes("/") || skill.includes("\\") || skill.includes("..")) {
     return undefined;
   }
+  // Codec boundary: callers hand us EITHER the canonical invocation name
+  // (`indigo:hello-world`) or an already-encoded local dir segment captured
+  // from a win32 path (`indigo%3Ahello-world`, Codex telemetry extraction).
+  // Normalize to canonical first — encoding an already-encoded name would
+  // look under `indigo%253A...` and miss the real wrapper — then encode for
+  // THIS host. Re-run the traversal guard on the decoded form: a crafted
+  // `%2F`/`%5C` escape must not smuggle a separator past the raw check.
+  const canonicalSkill = canonicalVaultSegmentSpelling(skill);
+  if (
+    canonicalSkill.includes("/") ||
+    canonicalSkill.includes("\\") ||
+    canonicalSkill.includes("..")
+  ) {
+    return undefined;
+  }
+  const localSkillDirName = encodeLocalVaultSegment(canonicalSkill);
   const candidates = [
-    path.join(hqRoot, ".claude", "skills", skill, "SKILL.md"),
-    path.join(hqRoot, ".agents", "skills", skill, "SKILL.md"),
+    path.join(hqRoot, ".claude", "skills", localSkillDirName, "SKILL.md"),
+    path.join(hqRoot, ".agents", "skills", localSkillDirName, "SKILL.md"),
   ];
+  // Colon-free names do not normalize (amplifier families are namespaced),
+  // so a win32 capture of a space-named skill's dir (`foo%20bar`) would
+  // re-encode to `foo%2520bar` and miss — also try the raw segment as-is.
+  if (skill !== localSkillDirName) {
+    candidates.push(
+      path.join(hqRoot, ".claude", "skills", skill, "SKILL.md"),
+      path.join(hqRoot, ".agents", "skills", skill, "SKILL.md"),
+    );
+  }
   for (const candidate of candidates) {
     try {
       const bytes = await fs.readFile(candidate);
@@ -854,7 +883,7 @@ export async function collectAndSendSkillTelemetry(
   // When `hqRoot` is omitted the map is empty → every event stays unattributed.
   const repoCompanyMap: RepoCompanyMap = opts.hqRoot
     ? await buildRepoCompanyMap(opts.hqRoot)
-    : { entries: [], bySlug: new Map() };
+    : { entries: [], bySlug: new Map(), foldsCase: false, ambiguous: new Set<string>() };
 
   // skillVersion resolution (US-015): resolve each skill's SKILL.md content hash
   // ONCE per run (skills repeat across a session) and stamp it onto every event.

package/src/telemetry.test.ts

@@ -33,24 +33,42 @@ interface StubClient extends TelemetryClientSurface {
   posts: UsageBatch[];
   /** Number of times `getTelemetryOptIn` was called. */
   optInCalls: number;
+  /** Every value handed to `setTelemetryOptIn`, in arrival order. */
+  optInSets: boolean[];
+  /** The options object passed alongside each `setTelemetryOptIn` call. */
+  optInSetOpts: Array<{ onlyIfUnset?: boolean } | undefined>;
 }
 
 function makeClient(opts: {
   optInResponse?: TelemetryOptInResponse | Error;
   postResponse?: UsageIngestResult | Error;
+  /** When set, `setTelemetryOptIn` rejects with this error. */
+  setOptInError?: Error;
+  /** `applied` value the conditional write reports back (default true). */
+  setOptInApplied?: boolean;
 } = {}): StubClient {
   const optInResponse = opts.optInResponse ?? { enabled: true, updatedAt: null };
   const postResponse = opts.postResponse ?? { ok: true, written: 0, skipped: [] };
 
   const posts: UsageBatch[] = [];
+  const optInSets: boolean[] = [];
+  const optInSetOpts: Array<{ onlyIfUnset?: boolean } | undefined> = [];
   const stub: StubClient = {
     posts,
     optInCalls: 0,
+    optInSets,
+    optInSetOpts,
     async getTelemetryOptIn() {
       this.optInCalls++;
       if (optInResponse instanceof Error) throw optInResponse;
       return optInResponse;
     },
+    async setTelemetryOptIn(enabled: boolean, setOpts?: { onlyIfUnset?: boolean }) {
+      optInSets.push(enabled);
+      optInSetOpts.push(setOpts);
+      if (opts.setOptInError) throw opts.setOptInError;
+      return { applied: opts.setOptInApplied ?? true };
+    },
     async postUsage(batch: UsageBatch) {
       posts.push(batch);
       if (postResponse instanceof Error) throw postResponse;
@@ -722,3 +740,226 @@ describe("collectAndSendTelemetry — companyUid attribution", () => {
     for (const ev of events) expect(ev.companyUid).toBe(COMPANY_UID);
   });
 });
+
+const CALLER = "prs_01CALLER";
+
+// ── Consent self-heal ────────────────────────────────────────────────────────
+//
+// Regression for the opt-in race: the installer writes the user's answer to
+// `~/.hq/menubar.json` (always succeeds) AND posts it to `/v1/usage/opt-in` —
+// but that post fires before the person entity exists, so it 404s and the
+// server attribute is never written. Absence read as `false`, the emitter went
+// silent, and the person showed as "not opted in" forever. Measured in prod:
+// 22 of 33 active Indigo members had NO attribute at all, against 2 genuine
+// opt-outs.
+//
+// The heal replays the answer the user already gave. It must fire ONLY on the
+// server's `unset` state, and must never invent or overwrite consent.
+
+describe("collectAndSendTelemetry — consent self-heal", () => {
+  let env: TestEnv;
+  beforeEach(() => {
+    env = setupEnv();
+  });
+  afterEach(() => teardownEnv(env));
+
+  // The cached answer must name the account it belongs to; an unbound record is
+  // deliberately not replayable (see the cross-account test below).
+  function writeMenubar(value: unknown, personUid: string | undefined = CALLER): void {
+    fs.writeFileSync(
+      env.menubarPath,
+      JSON.stringify({
+        telemetryEnabled: value,
+        ...(personUid ? { telemetryOptInPersonUid: personUid } : {}),
+      }),
+    );
+  }
+
+  it("re-asserts a local opt-IN when the server has no recorded consent", async () => {
+    writeMenubar(true);
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([true]);
+    expect(result.enabled).toBe(true);
+    expect(result.optInSource).toBe("menubar-reasserted");
+  });
+
+  it("re-asserts a local opt-OUT so the server records the real answer", async () => {
+    writeMenubar(false);
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([false]);
+    expect(result.enabled).toBe(false);
+  });
+
+  it("NEVER overwrites an explicit server opt-out", async () => {
+    // The user opted in on this machine at some point, then explicitly opted
+    // out account-wide. The account-wide answer must win.
+    writeMenubar(true);
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: "2026-06-19T16:11:09.939Z", unset: false },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([]);
+    expect(result.enabled).toBe(false);
+    expect(result.optInSource).toBe("server");
+  });
+
+  it("does not invent consent when no local answer exists", async () => {
+    // No menubar.json at all — we hold no answer, so we assert nothing.
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([]);
+    expect(result.enabled).toBe(false);
+  });
+
+  it("does not invent consent when the local value is not a boolean", async () => {
+    writeMenubar("yes");
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([]);
+    expect(result.enabled).toBe(false);
+  });
+
+  it("falls back to the server answer when the re-assert POST fails", async () => {
+    writeMenubar(true);
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+      setOptInError: new Error("network down"),
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([true]);
+    // Non-fatal: the run completes on the server's answer and retries next time.
+    expect(result.enabled).toBe(false);
+    expect(result.optInSource).toBe("server");
+  });
+
+  it("skips the heal entirely against an older server that omits `unset`", async () => {
+    writeMenubar(true);
+    const client = makeClient({ optInResponse: { enabled: false, updatedAt: null } });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([]);
+    expect(result.optInSource).toBe("server");
+  });
+});
+
+// The self-heal must be ATOMIC. Reading `unset` and replaying the local answer
+// are two requests; without a server-side condition another device could record
+// a real opt-out in between and the replay would clobber it.
+describe("collectAndSendTelemetry — self-heal is conditional", () => {
+  let env: TestEnv;
+  beforeEach(() => {
+    env = setupEnv();
+  });
+  afterEach(() => teardownEnv(env));
+
+  it("asks the server to write ONLY if the consent is still unset", async () => {
+    fs.writeFileSync(
+      env.menubarPath,
+      JSON.stringify({ telemetryEnabled: true, telemetryOptInPersonUid: CALLER }),
+    );
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+    });
+
+    await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSetOpts[0]).toMatchObject({ onlyIfUnset: true });
+  });
+
+  it("defers to the server when the conditional write loses the race", async () => {
+    // A real answer was recorded elsewhere between our GET and our POST.
+    fs.writeFileSync(
+      env.menubarPath,
+      JSON.stringify({ telemetryEnabled: true, telemetryOptInPersonUid: CALLER }),
+    );
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+      setOptInApplied: false,
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    // The stale local `true` must NOT win over the answer that landed first.
+    expect(result.enabled).toBe(false);
+    expect(result.optInSource).toBe("server");
+  });
+});
+
+// The cached consent lives in a per-MACHINE file. If two people sign in under
+// the same OS user it holds whoever answered LAST, so replaying it for a
+// different account would opt in someone who never consented.
+describe("collectAndSendTelemetry — consent replay is account-scoped", () => {
+  let env: TestEnv;
+  beforeEach(() => {
+    env = setupEnv();
+  });
+  afterEach(() => teardownEnv(env));
+
+  it("does NOT replay a cached answer belonging to a different account", async () => {
+    fs.writeFileSync(
+      env.menubarPath,
+      JSON.stringify({ telemetryEnabled: true, telemetryOptInPersonUid: "prs_01SOMEONE_ELSE" }),
+    );
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([]);
+    expect(result.enabled).toBe(false);
+  });
+
+  it("does NOT replay a legacy record with no account binding", async () => {
+    // Written before consent was bound to an account — we cannot prove whose
+    // answer it is, so the installer's post-sign-in upload is the recovery path.
+    fs.writeFileSync(env.menubarPath, JSON.stringify({ telemetryEnabled: true }));
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([]);
+    expect(result.enabled).toBe(false);
+  });
+
+  it("does NOT replay when the server cannot say who the caller is", async () => {
+    fs.writeFileSync(
+      env.menubarPath,
+      JSON.stringify({ telemetryEnabled: true, telemetryOptInPersonUid: CALLER }),
+    );
+    // Older server: no `personUid`, so the match cannot be proven.
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([]);
+    expect(result.enabled).toBe(false);
+  });
+});