@indigoai-us/hq-cloud 6.14.22 → 6.14.24

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);

package/src/watcher.test.ts

@@ -796,3 +796,36 @@ describe("PushEventEmitter — directory and delete tombstone handling", () => {
     ]);
   });
 });
+
+describe("TreeWatcher wire-key codec boundary (US-002)", () => {
+  it("emits the canonical vault key for an encoded win32 farm name (verbatim local name on POSIX)", () => {
+    const hqRoot = path.join(os.tmpdir(), "hq-watch-codec-test-root");
+    const clock = new FakeClock();
+    const watcher = new TreeWatcher({
+      hqRoot,
+      clock,
+      debounceMs: 100,
+      pathFilter: () => true,
+    });
+    const rels: string[] = [];
+    watcher.onChange((_first, batch) => {
+      if (batch) rels.push(...batch.paths.values());
+    });
+
+    watcher.handleEvent(
+      path.join(hqRoot, ".claude", "skills", "indigo%3Acall-prep-brief"),
+    );
+    clock.advance(200);
+
+    // The batch rel is a WIRE identifier (PushEvent.relativePath / targeted
+    // push route). On win32 the encoded local farm name must decode back to
+    // the canonical key or event-driven push re-mints the junk key family;
+    // on POSIX the local name IS the key verbatim (codec is identity there).
+    const expectedRel =
+      process.platform === "win32"
+        ? ".claude/skills/indigo:call-prep-brief"
+        : ".claude/skills/indigo%3Acall-prep-brief";
+    expect(rels).toEqual([expectedRel]);
+    watcher.dispose();
+  });
+});

package/src/watcher.ts

@@ -12,6 +12,7 @@ import { readFile, stat } from "node:fs/promises";
 import * as path from "path";
 import { watch } from "chokidar";
 import { createIgnoreFilter } from "./ignore.js";
+import { vaultKeyForLocalPath } from "./local-path-codec.js";
 import { isPersonalVaultExcluded } from "./personal-vault-exclusions.js";
 import {
   AGENCY_SYNC_REL,
@@ -734,7 +735,15 @@ export class TreeWatcher {
     // authoritative emit gate; the chokidar backend's `ignored` pre-filters
     // but a slipped-through (or synthetic test) path is re-checked here too.
     if (!this.shouldEmit(abs, isDir)) return;
-    const rel = path.relative(this.hqRoot, abs).split(path.sep).join("/");
+    // Codec boundary: the batch's relative path is a WIRE identifier — it
+    // becomes `PushEvent.relativePath` and the targeted-push route key — so
+    // a win32 local farm name (`indigo%3Ax`) must decode back to its
+    // canonical vault-key spelling (`indigo:x`) here. Emitting the encoded
+    // local name verbatim would mint a fresh junk key family on the wire
+    // (the mixed-version amplifier). The emit filter above still sees the
+    // raw local path: its exclusion patterns live in local-name space and
+    // none of them contain codec-reserved characters.
+    const rel = vaultKeyForLocalPath(this.hqRoot, abs);
     if (!this.pending.has(abs)) {
       const entryBytes = estimatePendingEntryBytes(abs, rel);
       if (