@indigoai-us/hq-cloud 6.7.1 → 6.9.0

package/src/cli/share.test.ts

@@ -158,7 +158,7 @@ describe("share", () => {
     expect(result.filesUploaded).toBe(1);
     expect(result.aborted).toBe(false);
     // Remote key must be company-relative, not hqRoot-relative
-    expect(uploadFile).toHaveBeenCalledWith(expect.anything(), testFile, "test.md");
+    expect(uploadFile).toHaveBeenCalledWith(expect.anything(), testFile, "test.md", undefined, expect.anything());
   });
 
   it("respects ignore rules", async () => {
@@ -207,7 +207,7 @@ describe("share", () => {
     });
 
     // Key is "knowledge/crawl.json", not "companies/acme/knowledge/crawl.json"
-    expect(uploadFile).toHaveBeenCalledWith(expect.anything(), nested, "knowledge/crawl.json");
+    expect(uploadFile).toHaveBeenCalledWith(expect.anything(), nested, "knowledge/crawl.json", undefined, expect.anything());
   });
 
   it("skips files outside the company folder with a warning", async () => {
@@ -333,7 +333,7 @@ describe("share", () => {
     });
 
     expect(result.filesUploaded).toBe(1);
-    expect(uploadFile).toHaveBeenCalledWith(expect.anything(), testFile, "changed.md");
+    expect(uploadFile).toHaveBeenCalledWith(expect.anything(), testFile, "changed.md", undefined, expect.anything());
   });
 
   it("populates conflictPaths and emits a conflict event when both local and remote drifted from journal", async () => {
@@ -586,6 +586,181 @@ describe("share", () => {
     expect(fs.readFileSync(testFile, "utf-8")).toBe("my-local-version");
   });
 
+  describe("conditional-write fence (If-Match / If-None-Match / 412)", () => {
+    const fence412 = () =>
+      Object.assign(new Error("Precondition failed"), {
+        name: "PreconditionFailed",
+      });
+
+    it("fences a PUT over an existing remote with If-Match on the observed etag", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const testFile = path.join(companyRoot, "fenced.md");
+      fs.writeFileSync(testFile, "local edit");
+
+      // Remote exists at the journal baseline; only local changed -> clean
+      // push, but the PUT must still assert the observed remote etag so a
+      // peer write landing between HEAD and PUT draws a 412 instead of
+      // being clobbered (HEAD->PUT TOCTOU).
+      const syncedAt = new Date(Date.now() - 60_000).toISOString();
+      vi.mocked(headRemoteFile).mockResolvedValueOnce({
+        lastModified: new Date(Date.parse(syncedAt) - 30_000),
+        etag: '"baseline-etag"',
+        size: 5,
+      });
+      const journalPath = path.join(stateDir, "sync-journal.acme.json");
+      fs.writeFileSync(
+        journalPath,
+        JSON.stringify({
+          version: "1",
+          lastSync: syncedAt,
+          files: {
+            "fenced.md": {
+              hash: "stale-local-hash",
+              size: 5,
+              syncedAt,
+              direction: "up",
+              remoteEtag: "baseline-etag",
+            },
+          },
+        }),
+      );
+
+      const result = await share({
+        paths: [testFile],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+      });
+
+      expect(result.filesUploaded).toBe(1);
+      expect(uploadFile).toHaveBeenCalledWith(
+        expect.anything(),
+        testFile,
+        "fenced.md",
+        undefined,
+        { ifMatch: '"baseline-etag"' },
+      );
+    });
+
+    it("fences a brand-new key with If-None-Match:* (create-only)", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const testFile = path.join(companyRoot, "brand-new.md");
+      fs.writeFileSync(testFile, "fresh");
+
+      vi.mocked(headRemoteFile).mockResolvedValueOnce(null);
+
+      await share({
+        paths: [testFile],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+      });
+
+      expect(uploadFile).toHaveBeenCalledWith(
+        expect.anything(),
+        testFile,
+        "brand-new.md",
+        undefined,
+        { ifNoneMatch: "*" },
+      );
+    });
+
+    it("412 under keep: conflict event + remote mirrored + ledger entry + NO journal stamp", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const testFile = path.join(companyRoot, "raced.md");
+      fs.writeFileSync(testFile, "my local bytes");
+
+      vi.mocked(headRemoteFile).mockResolvedValueOnce(null);
+      vi.mocked(uploadFile).mockRejectedValueOnce(fence412());
+      vi.mocked(downloadFile).mockImplementationOnce(async (_ctx, _key, dest) => {
+        fs.writeFileSync(dest as string, "the racing peer version");
+        return undefined as never;
+      });
+
+      const events: Array<{ type?: string; path?: string }> = [];
+      const result = await share({
+        paths: [testFile],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        onConflict: "keep",
+        onEvent: (e) => events.push(e as { type?: string }),
+      });
+
+      // Surfaced as a push conflict, not an error.
+      expect(result.conflictPaths).toEqual(["raced.md"]);
+      expect(result.filesUploaded).toBe(0);
+      expect(result.aborted).toBe(false);
+      expect(
+        events.some((e) => e.type === "conflict" && e.path === "raced.md"),
+      ).toBe(true);
+      // The racing remote bytes were preserved next to the local copy.
+      const mirrors = fs
+        .readdirSync(companyRoot)
+        .filter((f) => f.includes(".conflict-"));
+      expect(mirrors).toHaveLength(1);
+      // Local copy untouched.
+      expect(fs.readFileSync(testFile, "utf-8")).toBe("my local bytes");
+      // No journal stamp for the failed PUT — next pass re-evaluates fresh.
+      const journalPath = path.join(stateDir, "sync-journal.acme.json");
+      if (fs.existsSync(journalPath)) {
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        expect(journal.files?.["raced.md"]).toBeUndefined();
+      }
+    });
+
+    it("412 under overwrite: retries exactly once WITHOUT the fence (explicit consent)", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const testFile = path.join(companyRoot, "consented.md");
+      fs.writeFileSync(testFile, "clobber me in");
+
+      vi.mocked(headRemoteFile).mockResolvedValueOnce(null);
+      vi.mocked(uploadFile)
+        .mockRejectedValueOnce(fence412())
+        .mockResolvedValueOnce({ etag: '"retried-etag"' });
+
+      const result = await share({
+        paths: [testFile],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        onConflict: "overwrite",
+      });
+
+      expect(result.filesUploaded).toBe(1);
+      const calls = vi.mocked(uploadFile).mock.calls;
+      expect(calls).toHaveLength(2);
+      // First attempt fenced; retry deliberately unfenced.
+      expect(calls[0][4]).toEqual({ ifNoneMatch: "*" });
+      expect(calls[1][4]).toBeUndefined();
+    });
+
+    it("412 under abort: halts the pass", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const testFile = path.join(companyRoot, "halting.md");
+      fs.writeFileSync(testFile, "stop here");
+
+      vi.mocked(headRemoteFile).mockResolvedValueOnce(null);
+      vi.mocked(uploadFile).mockRejectedValueOnce(fence412());
+
+      const result = await share({
+        paths: [testFile],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        onConflict: "abort",
+      });
+
+      expect(result.aborted).toBe(true);
+      expect(result.conflictPaths).toEqual(["halting.md"]);
+    });
+  });
+
   it("scoped push (plan-exceeds-grant): syncs the in-scope subset, skips out-of-scope paths, never aborts (feedback_ded09d56)", async () => {
     // Real case (look-optic): a FILE_ACL grant covered {knowledge,policies,
     // workers}/* + company.yaml, but the upload plan also contained
@@ -694,6 +869,45 @@ describe("share", () => {
     expect(errs[0].message).toMatch(/outside granted ACL scope/i);
   });
 
+  it("a Forbidden HEAD (presigned-transport denial) skips the key — NEVER an unconditional PUT", async () => {
+    // Regression for the 2026-06-10..12 vault regression storm: the presigned
+    // transport used to map per-key denials and signed-GET 403s to `null`,
+    // which `processUploadItem` read as "no remote object" — skipping every
+    // conflict guard and blind-PUTting this machine's (possibly stale) bytes
+    // over a newer remote. The transport now throws `name: "Forbidden"`
+    // (SDK HeadObject parity); this locks the share side of that contract:
+    // a Forbidden HEAD must skip the key, emit a named error, and issue NO PUT.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const staleFile = path.join(companyRoot, "stale-local.md");
+    fs.writeFileSync(staleFile, "stale local bytes\n");
+
+    vi.mocked(headRemoteFile).mockImplementation(async () => {
+      const err = new Error(
+        "Access denied for stale-local.md: presigned HEAD returned 403",
+      );
+      (err as { name: string }).name = "Forbidden";
+      throw err;
+    });
+
+    const events: Array<{ type?: string; path?: string; message?: string }> = [];
+    const result = await share({
+      paths: [staleFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onEvent: (e) => events.push(e as { type?: string }),
+    });
+
+    // The one thing that must never happen: a PUT issued with unknown remote state.
+    expect(vi.mocked(uploadFile)).not.toHaveBeenCalled();
+    expect(result.filesUploaded).toBe(0);
+    expect(result.aborted).toBe(false);
+    const errs2 = events.filter((e) => e.type === "error") as Array<{ path?: string }>;
+    expect(errs2).toHaveLength(1);
+    expect(errs2[0].path).toBe("stale-local.md");
+  });
+
   it("uploads (no conflict) when only the local side changed since last sync", async () => {
     // Regression for hq-cloud#<conflict-detection>: a local edit to a file
     // that exists on S3 used to trigger a push conflict because the
@@ -835,12 +1049,14 @@ describe("share", () => {
       testFile,
       "attribution.md",
       { userSub: "abc-123", email: "alice@example.com" },
+      expect.anything(),
     );
   });
 
   it("omits author arg when not provided (back-compat)", async () => {
-    // share() must remain a 3-arg call to uploadFile when no author is
-    // configured — older test stubs and external integrations rely on it.
+    // With no author configured the author slot is undefined (the
+    // conditional-write fence appended a 5th arg in 6.9.0, so the legacy
+    // 3-arg shape grew to 5; author-less calls pass undefined explicitly).
     const companyRoot = path.join(tmpDir, "companies", "acme");
     fs.mkdirSync(companyRoot, { recursive: true });
     const testFile = path.join(companyRoot, "no-author.md");
@@ -857,6 +1073,8 @@ describe("share", () => {
       expect.anything(),
       testFile,
       "no-author.md",
+      undefined,
+      expect.anything(),
     );
   });
 
@@ -1032,7 +1250,7 @@ describe("share", () => {
     expect(fetchMock).not.toHaveBeenCalled();
     // The S3 upload sees the pre-vended credentials, not freshly-vended ones.
     // (uploadFile is mocked, so we just verify it was called with our ctx.)
-    expect(uploadFile).toHaveBeenCalledWith(ctx, testFile, "from-appbar.md");
+    expect(uploadFile).toHaveBeenCalledWith(ctx, testFile, "from-appbar.md", undefined, expect.anything());
   });
 
   it("falls back to entityContext.slug when company is not specified", async () => {
@@ -1055,6 +1273,8 @@ describe("share", () => {
       expect.anything(),
       testFile,
       "no-company-arg.md",
+      undefined,
+      expect.anything(),
     );
   });
 
@@ -1088,7 +1308,7 @@ describe("share", () => {
     expect(result.filesUploaded).toBe(1);
     expect(fetchMock).not.toHaveBeenCalled();
     // The original (still-valid-for-30s) credentials must have been used as-is.
-    expect(uploadFile).toHaveBeenCalledWith(expiringCtx, testFile, "race.md");
+    expect(uploadFile).toHaveBeenCalledWith(expiringCtx, testFile, "race.md", undefined, expect.anything());
   });
 
   it("throws when both vaultConfig and entityContext are provided (ambiguous)", async () => {
@@ -2151,6 +2371,8 @@ describe("share", () => {
       expect.anything(),
       expect.stringContaining("real.md"),
       "skills/real.md",
+      undefined,
+      expect.anything(),
     );
     // Spy was called once total — the conflict mirror never reaches uploadFile.
     // (Asserted by count above; the explicit non-call below is defensive.)
@@ -2634,7 +2856,7 @@ describe("share", () => {
       });
 
       expect(result.filesUploaded).toBe(1);
-      expect(uploadFile).toHaveBeenCalledWith(expect.anything(), outsideFile, "stray.md");
+      expect(uploadFile).toHaveBeenCalledWith(expect.anything(), outsideFile, "stray.md", undefined, expect.anything());
     });
 
     it("uploads 0-byte files (e.g. .gitkeep placeholders)", async () => {
@@ -2658,7 +2880,7 @@ describe("share", () => {
       });
 
       expect(result.filesUploaded).toBe(1);
-      expect(uploadFile).toHaveBeenCalledWith(expect.anything(), gitkeep, "projects/.gitkeep");
+      expect(uploadFile).toHaveBeenCalledWith(expect.anything(), gitkeep, "projects/.gitkeep", undefined, expect.anything());
     });
 
     it("personalMode=true + skipUnchanged honors the personal-journal hash", async () => {
@@ -2737,6 +2959,8 @@ describe("share", () => {
         expect.anything(),
         "target.md",
         "link.md",
+        undefined,
+        expect.anything(),
       );
       // The link itself must NOT be uploaded as a regular file. Pre-fix,
       // fs.statSync(link) followed the link and uploadFile got called with
@@ -2774,11 +2998,15 @@ describe("share", () => {
         expect.anything(),
         realPolicy,
         "policies/real.md",
+        undefined,
+        expect.anything(),
       );
       expect(uploadSymlink).toHaveBeenCalledWith(
         expect.anything(),
         "real.md",
         "policies/link.md",
+        undefined,
+        expect.anything(),
       );
     });
 
@@ -2811,6 +3039,8 @@ describe("share", () => {
         expect.anything(),
         externalTarget,
         "knowledge",
+        undefined,
+        expect.anything(),
       );
       // No "outside company folder" warning for this case.
       expect(warnSpy).not.toHaveBeenCalledWith(
@@ -2876,6 +3106,8 @@ describe("share", () => {
         expect.anything(),
         target,
         "case-key.md",
+        undefined,
+        expect.anything(),
       );
     });
 
@@ -2917,6 +3149,8 @@ describe("share", () => {
         expect.anything(),
         externalTarget,
         "knowledge",
+        undefined,
+        expect.anything(),
       );
       expect(uploadFile).not.toHaveBeenCalledWith(
         expect.anything(),
@@ -2952,6 +3186,8 @@ describe("share", () => {
         expect.anything(),
         realDir,
         "linked-dir",
+        undefined,
+        expect.anything(),
       );
       // Crucially, no upload of the dir's contents.
       const calls = vi.mocked(uploadFile).mock.calls;

package/src/cli/share.ts

@@ -22,6 +22,7 @@ import {
 } from "../s3.js";
 import * as crypto from "crypto";
 import type { UploadAuthor } from "../s3.js";
+import type { PutPrecondition } from "../object-io.js";
 import {
   readJournal,
   writeJournal,
@@ -693,6 +694,20 @@ function isAccessDenied(err: unknown): boolean {
   return false;
 }
 
+/**
+ * A conditional-write fence rejection — the SDK's 412 (`name:
+ * "PreconditionFailed"`) or the presigned transport's mirror of it. Means
+ * the remote moved past the etag this pass inspected (If-Match) or an
+ * object appeared at a key we believed absent (If-None-Match). Always a
+ * conflict, never a transport failure.
+ */
+function isPreconditionFailed(err: unknown): boolean {
+  if (err && typeof err === "object" && "name" in err) {
+    return (err as { name?: unknown }).name === "PreconditionFailed";
+  }
+  return false;
+}
+
 /**
  * Wrap an existing path filter (ignore filter, optionally already wrapped with
  * the personal-vault defaults) so that paths OUTSIDE the run's ACL `prefixSet`
@@ -1280,11 +1295,29 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     // after the user signaled abort.
     if (aborted) return;
 
+    // Conditional-write fence (storage-level backstop for the entire
+    // stale-clobber class). Every PUT asserts the remote state this pass
+    // just inspected:
+    //   - remote exists  → If-Match on the observed etag ("replace exactly
+    //     what I HEAD'd"). Closes the HEAD→PUT TOCTOU: a peer's write
+    //     landing in the window makes S3 itself reject with 412 instead of
+    //     this machine silently regressing the object.
+    //   - remote absent  → If-None-Match:* ("create only"). If the HEAD was
+    //     wrong about absence (any transport/state bug — the 2026-06-10..12
+    //     regression storm's shape), the PUT 412s instead of clobbering.
+    // Enforced natively on the SDK transport; on the presigned transport it
+    // activates when files-presign signs the headers (see object-io.ts).
+    const precondition: PutPrecondition = remoteMeta
+      ? { ifMatch: remoteMeta.etag }
+      : { ifNoneMatch: "*" };
+
     // Upload — symlinks go through uploadSymlink (zero-byte body + target
     // metadata), regular files through uploadFile (file contents). The
     // discriminator is item.kind set by computePushPlan; both branches
-    // converge on the same journal/event update path below.
-    try {
+    // converge on the same journal/event update path below. Factored into a
+    // closure so the 412 "overwrite" resolution below can re-run it without
+    // the fence after explicit user consent.
+    const performUpload = async (pc: PutPrecondition | undefined): Promise<void> => {
       const isSymlinkUpload = item.kind === "symlink";
       // Capture lstat post-upload so size + mtimeMs stamped into the
       // journal reflect the bytes we actually shipped. lstat (not stat)
@@ -1296,12 +1329,8 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       const mtimeMs = lstat.mtimeMs;
 
       const { etag } = isSymlinkUpload
-        ? options.author
-          ? await uploadSymlink(ctx, item.target, relativePath, options.author)
-          : await uploadSymlink(ctx, item.target, relativePath)
-        : options.author
-          ? await uploadFile(ctx, absolutePath, relativePath, options.author)
-          : await uploadFile(ctx, absolutePath, relativePath);
+        ? await uploadSymlink(ctx, item.target, relativePath, options.author, pc)
+        : await uploadFile(ctx, absolutePath, relativePath, options.author, pc);
 
       // Update journal with optional message; capture the post-upload ETag
       // so the next sync can distinguish "remote moved since we last wrote"
@@ -1323,7 +1352,86 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
         bytes: size,
         ...(message ? { message } : {}),
       });
+    };
+
+    try {
+      await performUpload(precondition);
     } catch (err) {
+      if (isPreconditionFailed(err)) {
+        // The fence fired: the remote moved past (If-Match) or appeared at
+        // (If-None-Match) this key between our HEAD and the PUT — exactly
+        // the race the fence exists to catch. Surface as a push conflict;
+        // never silently overwrite.
+        conflictPaths.push(relativePath);
+        const resolution = await resolveConflict(
+          { path: relativePath, localHash, direction: "push" },
+          onConflict,
+        );
+        emit({
+          type: "conflict",
+          path: relativePath,
+          direction: "push",
+          resolution,
+        });
+        if (resolution === "abort") {
+          aborted = true;
+          abortFlightConflictPaths = [...conflictPaths];
+          return;
+        }
+        if (resolution === "overwrite") {
+          // Explicit clobber consent — retry once without the fence. A
+          // second failure falls through to the generic error emit.
+          try {
+            await performUpload(undefined);
+          } catch (retryErr) {
+            emit({
+              type: "error",
+              path: relativePath,
+              message:
+                retryErr instanceof Error ? retryErr.message : String(retryErr),
+            });
+          }
+          return;
+        }
+        // keep/skip: preserve the racing remote next to the local copy so
+        // both versions survive — same mirror routine as the fresh-collision
+        // branch above.
+        try {
+          const detectedAt = new Date().toISOString();
+          const machineId = readShortMachineId(hqRoot);
+          const originalRelative = path.relative(hqRoot, absolutePath);
+          const conflictRelative = buildConflictPath(
+            originalRelative,
+            detectedAt,
+            machineId,
+          );
+          const conflictAbs = path.join(hqRoot, conflictRelative);
+          await downloadFile(ctx, relativePath, conflictAbs);
+          appendConflictEntry(hqRoot, {
+            id: buildConflictId(originalRelative, detectedAt),
+            originalPath: originalRelative,
+            conflictPath: conflictRelative,
+            detectedAt,
+            side: "push",
+            machineId,
+            localHash,
+            // remoteMeta (if any) predates the racing write that fired the
+            // fence — record what we knew ("" when the key was believed
+            // absent); the mirror file carries the authoritative remote bytes.
+            remoteHash: remoteMeta ? normalizeEtag(remoteMeta.etag) : "",
+          });
+        } catch (mirrorErr) {
+          emit({
+            type: "error",
+            path: relativePath,
+            message: `conflict mirror write failed: ${
+              mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)
+            }`,
+          });
+        }
+        filesSkipped++;
+        return;
+      }
       emit({
         type: "error",
         path: relativePath,

package/src/cognito-auth.ts

@@ -580,9 +580,17 @@ export async function getValidAccessToken(
 
   // Machine identities (company agents) never refresh or open a browser —
   // they re-mint via USER_PASSWORD_AUTH on demand.
+  // Machine identities return the ID token: every hq-cloud caller of this
+  // getter talks to the VAULT API, whose authorizer accepts ID tokens — and
+  // the agent's identity claims (custom:entityType/entityUid) ride the ID
+  // token ONLY. Returning the access token made the first post-cutover
+  // agent box (Petyr, 2026-06-12) resolve as NOBODY: /membership/me -> []
+  // -> 'setup-needed' forever, while the identical call with the ID token
+  // returned its membership. (Consumers needing token_use=access — e.g.
+  // the deploy API — pick tokens per call in hq-cli, not here.)
   if (isMachineIdentity()) {
     const machine = await getValidMachineTokens(config);
-    return machine.accessToken;
+    return machine.idToken;
   }
 
   let cached = loadCachedTokens();

package/src/machine-auth.test.ts

@@ -298,7 +298,7 @@ describe("getValidMachineTokens", () => {
 // ---------------------------------------------------------------------------
 
 describe("getValidAccessToken in machine mode", () => {
-  it("mints via machine creds instead of refreshing or opening a browser", async () => {
+  it("mints via machine creds and returns the ID token (vault-API identity)", async () => {
     writeCreds();
     const { calls } = stubMintFetch();
     const { getValidAccessToken } = await importModule();
@@ -309,6 +309,8 @@ describe("getValidAccessToken in machine mode", () => {
     const claims = JSON.parse(
       Buffer.from(token.split(".")[1], "base64url").toString(),
     );
-    expect(claims.token_use).toBe("access");
+    // ID, NOT access: agent identity rides the ID token; the access-token
+    // return lobotomized first-sync on the first post-cutover box.
+    expect(claims.token_use).toBe("id");
   });
 });