@indigoai-us/hq-cloud 6.11.8 → 6.11.10

package/src/personal-vault.ts

@@ -126,7 +126,8 @@ export function computePersonalVaultPaths(
     ? computePersonalCompanySubdirs(hqRoot, opts.teamSyncedSlugs)
     : [];
   const continuity = computeContinuityPointerPaths(hqRoot);
-  return [...topLevel, ...manifest, ...companySubdirs, ...continuity];
+  const agency = computeAgencySyncPaths(hqRoot);
+  return [...topLevel, ...manifest, ...companySubdirs, ...continuity, ...agency];
 }
 
 /**
@@ -213,6 +214,40 @@ export function computeContinuityPointerPaths(hqRoot: string): string[] {
   return out;
 }
 
+/**
+ * Fixed relative path (forward-slash, hq-root-relative) of the agency
+ * workspace subtree. See {@link computeAgencySyncPaths}.
+ */
+export const AGENCY_SYNC_REL = "workspace/agency";
+
+/**
+ * Compute the absolute path of the agency-workspace carve-out:
+ * `workspace/agency/` (the whole subtree).
+ *
+ * Like the session-continuity pointer above, this pierces the `workspace/`
+ * top-level exclusion for ONE specific subtree. hq-pack-agency teams keep
+ * their cross-session chat.jsonl inboxes and roster/state under
+ * `workspace/agency/<company>/<team>/`; that state must travel across machines
+ * so an agency team picked up on machine B sees the same conversation and
+ * roster it had on machine A. The rest of `workspace/` (session scratch,
+ * locks, reports, full thread history) stays machine-local.
+ *
+ * Returns the directory path when it exists; share()'s per-file walk handles
+ * recursion, and the nested personal-vault exclusions still apply to files
+ * inside it (e.g. a stray `node_modules/` or `.env`). Fail-soft: a missing or
+ * unreadable `workspace/agency/` returns []. Callers tolerate empty arrays —
+ * same contract as the manifest + continuity special-cases.
+ */
+export function computeAgencySyncPaths(hqRoot: string): string[] {
+  const agencyDir = path.join(hqRoot, "workspace", "agency");
+  try {
+    if (fs.statSync(agencyDir).isDirectory()) return [agencyDir];
+  } catch {
+    // No agency workspace on this machine — nothing to carry.
+  }
+  return [];
+}
+
 /**
  * Discover `companies/{slug}/` subdirs that should sync to the personal
  * bucket as a fallback for companies the operator has not designated as

package/src/skill-telemetry.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+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";
@@ -923,3 +923,128 @@ describe("collectAndSendSkillTelemetry — hqRoot scoping", () => {
     await fs.rm(tmp, { recursive: true, force: true });
   });
 });
+
+// ── companyUid edge attribution (US-002) ────────────────────────────────────────
+
+describe("collectAndSendSkillTelemetry — companyUid attribution", () => {
+  const COMPANY_UID = "cmp_01INDIGOSKILL";
+
+  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);
+  }
+
+  /** Write a manifest mapping `repos/private/hq-cloud` → COMPANY_UID under hqRoot. */
+  async function writeManifest(hqRoot: string): Promise<void> {
+    await fs.mkdir(path.join(hqRoot, "companies"), { recursive: true });
+    await fs.writeFile(
+      path.join(hqRoot, "companies", "manifest.yaml"),
+      `companies:\n  indigo:\n    repos:\n      - repos/private/hq-cloud\n    cloud_uid: ${COMPANY_UID}\n`,
+      "utf-8",
+    );
+  }
+
+  it("stamps companyUid when cwd is inside a company repo, omits it otherwise", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "skill-tel-co-"));
+    const hqRoot = tmp; // real dir so the manifest's repo path resolves under it
+    await writeManifest(hqRoot);
+    const projects = path.join(tmp, "projects");
+    const dir = path.join(projects, "-p");
+    await fs.mkdir(dir, { recursive: true });
+
+    const inRepo = path.join(hqRoot, "repos/private/hq-cloud");
+    const atRoot = hqRoot; // inside scope, but not inside any mapped repo
+    await fs.writeFile(
+      path.join(dir, "s.jsonl"),
+      [
+        // cwd inside the company repo → attributed.
+        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.
+        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" } }] } }),
+      ].join("\n") + "\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(2);
+    const events = captured.flatMap((b) => b.events);
+    const bySkill = new Map(events.map((e) => [e.skill, e]));
+    expect(bySkill.get("deploy")!.companyUid).toBe(COMPANY_UID);
+    expect("companyUid" in bySkill.get("indigo:hello-world")!).toBe(false);
+    // Never the reserved sentinel.
+    for (const e of events) expect(e.companyUid).not.toBe("unattributed");
+
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  it("parses the manifest once per run (cache), not per event", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "skill-tel-cache-"));
+    const hqRoot = tmp;
+    await writeManifest(hqRoot);
+    const projects = path.join(tmp, "projects");
+    const dir = path.join(projects, "-p");
+    await fs.mkdir(dir, { recursive: true });
+    const inRepo = path.join(hqRoot, "repos/private/hq-cloud");
+    await fs.writeFile(
+      path.join(dir, "s.jsonl"),
+      Array.from({ length: 4 }, (_, i) =>
+        row({ type: "user", sessionId: "s1", timestamp: `2026-06-10T10:0${i}:00Z`, cwd: inRepo, uuid: `u${i}`, message: { role: "user", content: "<command-name>/deploy</command-name>" } }),
+      ).join("\n") + "\n",
+      "utf-8",
+    );
+
+    const manifestPath = path.join(hqRoot, "companies", "manifest.yaml");
+    const realReadFile = fs.readFile;
+    let manifestReads = 0;
+    const spy = vi
+      .spyOn(fs, "readFile")
+      .mockImplementation((async (p: Parameters<typeof realReadFile>[0], ...rest: unknown[]) => {
+        if (typeof p === "string" && p === manifestPath) manifestReads++;
+        // @ts-expect-error pass-through to the real implementation
+        return realReadFile(p, ...rest);
+      }) as typeof realReadFile);
+
+    const captured: SkillInvocationBatch[] = [];
+    try {
+      await collectAndSendSkillTelemetry({
+        client: stubClient(captured),
+        machineId: "m",
+        installerVersion: "t",
+        hqRoot,
+        claudeProjectsRoot: projects,
+        codexSessionsRoot: path.join(tmp, "codex"),
+        cursorPath: path.join(tmp, "cursor.json"),
+      });
+    } finally {
+      spy.mockRestore();
+    }
+
+    expect(manifestReads).toBe(1);
+    const events = captured.flatMap((b) => b.events);
+    expect(events).toHaveLength(4);
+    for (const e of events) expect(e.companyUid).toBe(COMPANY_UID);
+
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+});

package/src/skill-telemetry.ts

@@ -59,6 +59,11 @@ import { promises as fs } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
+import {
+  buildRepoCompanyMap,
+  resolveCompanyForCwd,
+  type RepoCompanyMap,
+} from "./company-resolver.js";
 import type {
   SkillInvocationBatch,
   SkillInvocationIngestResult,
@@ -533,8 +538,15 @@ export function extractCodexSkillToolEvents(
   ];
 }
 
-/** Shape the event for the wire. Drops raw args unless explicitly enabled. */
-function toWireRow(ev: SkillEvent): Record<string, unknown> {
+/** Shape the event for the wire. Drops raw args unless explicitly enabled.
+ *
+ *  `companyUid` (US-002): the caller resolves the event's `cwd` → owning company
+ *  (`resolveCompanyForCwd`) and passes that `cmp_*` uid here. It is on the
+ *  server's KEEP allowlist (`apps/hq-pro/src/vault-service/handlers/
+ *  skill-invocations.ts`). When undefined (cwd maps to no company repo) the
+ *  field is OMITTED — the server treats absence as unattributed/personal. The
+ *  reserved value `unattributed` is never produced. */
+function toWireRow(ev: SkillEvent, companyUid?: string): Record<string, unknown> {
   const row: Record<string, unknown> = {
     skill: ev.skill,
     source: ev.source,
@@ -544,6 +556,7 @@ function toWireRow(ev: SkillEvent): Record<string, unknown> {
   if (ev.timestamp !== undefined) row.timestamp = ev.timestamp;
   if (ev.uuid !== undefined) row.uuid = ev.uuid;
   if (ev.cwd !== undefined) row.cwd = ev.cwd;
+  if (companyUid !== undefined) row.companyUid = companyUid;
   // INCLUDE_ARGS_PREVIEW is intentionally a compile-time constant `false`;
   // the guarded branch documents the (currently disabled) egress path.
   if (INCLUDE_ARGS_PREVIEW) {
@@ -643,6 +656,13 @@ export async function collectAndSendSkillTelemetry(
   const normalizePath = (p: string): string => (p.length > 1 ? p.replace(/\/+$/, "") : p);
   const scopeCwd = opts.hqRoot !== undefined ? normalizePath(opts.hqRoot) : undefined;
 
+  // Company attribution (US-002): parse the manifest ONCE per run and reuse the
+  // repo-path→companyUid map for every event below. No per-event manifest read.
+  // When `hqRoot` is omitted the map is empty → every event stays unattributed.
+  const repoCompanyMap: RepoCompanyMap = opts.hqRoot
+    ? await buildRepoCompanyMap(opts.hqRoot)
+    : { entries: [] };
+
   // 1. Opt-in check — reuse the same gate as token telemetry.
   let enabled: boolean;
   let optInSource: CollectSkillTelemetryResult["optInSource"];
@@ -788,7 +808,10 @@ export async function collectAndSendSkillTelemetry(
             continue;
           }
         }
-        sourced.push({ row: toWireRow(ev), filePath, endOffset });
+        // Resolve cwd → owning company (cmp_* uid) from the per-run map.
+        // Unresolved → undefined → companyUid omitted (unattributed/personal).
+        const companyUid = resolveCompanyForCwd(ev.cwd, repoCompanyMap);
+        sourced.push({ row: toWireRow(ev, companyUid), filePath, endOffset });
         fileScans[filePath].eventCount++;
       }
     }

package/src/sync/event-sync.test.ts

@@ -376,6 +376,7 @@ describe("createRefreshingSqsClient", () => {
 function pushEvent(overrides: Partial<PushEvent> = {}): PushEvent {
   return {
     relativePath: "companies/indigo/docs/a.md",
+    kind: "upsert",
     contentHash: `sha256:${"a".repeat(64)}`,
     mtime: "2026-06-10T12:00:00.000Z",
     originDeviceId: "peer-device",
@@ -469,6 +470,25 @@ describe("startEventSync", () => {
       true,
     );
 
+    // Peer delete tombstone → bridged into syncFn. The runner handles safety by
+    // running a targeted pull; it does not unlink directly from this payload.
+    await waitForPoll();
+    deliverNext!(
+      JSON.stringify({
+        relativePath: "companies/indigo/deleted.md",
+        kind: "delete",
+        originDeviceId: "peer-device",
+        originTenantId: "prs_tenant",
+        sequenceNumber: 3,
+        eventTimestamp: "2026-06-10T12:01:00.000Z",
+      } satisfies PushEvent),
+    );
+    await vi.waitFor(() => expect(syncCalls).toHaveLength(2));
+    expect(syncCalls[1]).toMatchObject({
+      kind: "delete",
+      relativePath: "companies/indigo/deleted.md",
+    });
+
     await handles!.dispose();
   });
 
@@ -522,6 +542,7 @@ describe("startEventSync", () => {
     await vi.waitFor(() => expect(published).toHaveLength(1));
     const ev = published[0];
     expect(ev.relativePath).toBe("docs/self.ts");
+    expect(ev.kind).toBe("upsert");
     expect(ev.originDeviceId).toBe("this-device");
     expect(ev.originTenantId).toBe("prs_tenant");
     // Wall-clock sequence numbers (restart-safe monotonicity).

package/src/sync/feature-flags.test.ts

@@ -49,6 +49,7 @@ import type { TreeChangeBatch } from "../watcher.js";
 function fakePushEvent(overrides: Partial<PushEvent> = {}): PushEvent {
   return {
     relativePath: "personal/notes/a.md",
+    kind: "upsert",
     contentHash: `sha256:${"a".repeat(64)}`,
     mtime: "2026-05-21T12:00:00.000Z",
     originDeviceId: "device-1",
@@ -178,6 +179,34 @@ describe("HttpPushTransport — POST /sync/push", () => {
     expect(decodePushEvent(init.body)).toEqual(event);
   });
 
+  it("POSTs a delete tombstone without contentHash or mtime", async () => {
+    const { fetch, calls } = makeFetch({ ok: true, status: 200 });
+    const transport = new HttpPushTransport({
+      apiUrl: "https://vault-api.example.com/",
+      authToken: "tok-123",
+      fetchImpl: fetch,
+    });
+    const event = fakePushEvent({
+      kind: "delete",
+      contentHash: undefined,
+      mtime: undefined,
+    });
+
+    await transport.publish(event);
+
+    expect(calls).toHaveLength(1);
+    const body = (calls[0].init as { body: string }).body;
+    expect(JSON.parse(body)).toEqual({
+      relativePath: "personal/notes/a.md",
+      kind: "delete",
+      originDeviceId: "device-1",
+      originTenantId: "indigo",
+      sequenceNumber: 0,
+      eventTimestamp: "2026-05-21T12:00:01.000Z",
+    });
+    expect(decodePushEvent(body)).toEqual(JSON.parse(body));
+  });
+
   it("resolves the auth token per-request via an async getter (self-heals across refresh)", async () => {
     const { fetch, calls } = makeFetch();
     let n = 0;
@@ -287,6 +316,7 @@ describe("PushEventEmitter — emit, gating, failure handling", () => {
     expect(published).toHaveLength(1);
     const e = published[0];
     expect(e.relativePath).toBe(REL);
+    expect(e.kind).toBe("upsert");
     expect(e.originTenantId).toBe("indigo");
     expect(e.originDeviceId).toBe("dev-1");
     const expectedHex = createHash("sha256").update("hello world").digest("hex");
@@ -350,7 +380,7 @@ describe("PushEventEmitter — emit, gating, failure handling", () => {
     expect(onError.mock.calls[0][1]).toMatchObject({ relativePath: REL });
   });
 
-  it("a missing file (hash/stat race) is surfaced, other paths still ship", async () => {
+  it("a missing file emits a delete tombstone, and other paths still ship", async () => {
     const published: PushEvent[] = [];
     const onError = vi.fn();
     const emitter = new PushEventEmitter({
@@ -362,9 +392,15 @@ describe("PushEventEmitter — emit, gating, failure handling", () => {
     });
     // REL exists; "ghost.md" does not.
     await emitter.emitForBatch(batchFor(REL, "ghost.md"));
-    expect(published.map((e) => e.relativePath)).toEqual([REL]);
-    expect(onError).toHaveBeenCalledTimes(1);
-    expect(onError.mock.calls[0][1]).toMatchObject({ relativePath: "ghost.md" });
+    expect(published.map((e) => e.relativePath).sort()).toEqual([
+      REL,
+      "ghost.md",
+    ].sort());
+    const tombstone = published.find((e) => e.relativePath === "ghost.md");
+    expect(tombstone).toMatchObject({ kind: "delete" });
+    expect(tombstone).not.toHaveProperty("contentHash");
+    expect(tombstone).not.toHaveProperty("mtime");
+    expect(onError).not.toHaveBeenCalled();
   });
 
   it("end-to-end: emit → HttpPushTransport POST with a valid schema (mocked fetch)", async () => {

package/src/sync/index.ts

@@ -13,7 +13,11 @@ export {
   encodePushEvent,
   decodePushEvent,
 } from "./push-event.js";
-export type { PushEvent, PushEventDecodeIssue } from "./push-event.js";
+export type {
+  PushEvent,
+  PushEventInput,
+  PushEventDecodeIssue,
+} from "./push-event.js";
 
 export { NoopPushTransport, HttpPushTransport } from "./push-transport.js";
 export type {

package/src/sync/logger.test.ts

@@ -70,6 +70,7 @@ async function until(predicate: () => boolean, timeoutMs = 1000): Promise<void>
 function makeEvent(overrides: Partial<PushEvent> = {}): PushEvent {
   return {
     relativePath: "companies/indigo/notes.md",
+    kind: "upsert",
     contentHash:
       "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
     mtime: "2026-05-21T12:34:56.000Z",

package/src/sync/metrics.test.ts

@@ -82,6 +82,7 @@ const QUEUE_URL =
 function makeEvent(overrides: Partial<PushEvent> = {}): PushEvent {
   return {
     relativePath: "companies/indigo/notes.md",
+    kind: "upsert",
     contentHash:
       "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
     mtime: "2026-05-21T12:34:56.000Z",

package/src/sync/pull-scope.ts

@@ -35,7 +35,7 @@ import type {
  */
 export interface PullScopeClient {
   listMyMemberships(): Promise<
-    Array<{ companyUid: string; membershipKey: string }>
+    Array<{ companyUid: string; membershipKey: string; role?: string }>
   >;
   getMembershipSyncConfig?: (
     membershipId: string,
@@ -82,6 +82,31 @@ export async function resolvePullScope(
     const memberships = await client.listMyMemberships();
     const m = memberships.find((x) => x.companyUid === companyUid);
     if (!m) return { syncMode: "all" };
+    // OWNER role-bypass (feedback_67bdb8a4 / feedback_a46c3b37). An owner's
+    // effective vault access is the WHOLE company by role — the data plane
+    // resolves owner to `admin` on every key (`resolveEffectivePermission`'s
+    // role bypass; presign's `viewOthersFiles` is unconditional for owners).
+    // But the scope resolution below derives `shared` scope from
+    // `listMyExplicitGrants`, and that endpoint DELIBERATELY EXCLUDES the
+    // owner/admin role bypass — it answers "what is explicitly shared with
+    // me", not "what can I touch by role" (see hq-pro files-grants handler).
+    // An owner who owns by role (not by explicit grant) therefore resolves to
+    // an empty/sparse prefixSet, so the push uploads NOTHING (every path is
+    // filtered out by `wrapFilterWithScope`) and any in-role write — including
+    // a brand-new top-level project prefix the owner just created — is rejected
+    // by the server as `403 SCOPE_EXCEEDS_PARENT`. An owner has no meaningful
+    // "shared subset": they own everything, so their effective sync scope IS
+    // the full vault. Resolve them to `all` directly — restoring the pre-
+    // pull-scope-refactor behavior (owners always journaled the whole company).
+    // This is checked BEFORE the sync-config fetch so it holds even if a stray
+    // `shared` row exists for the owner. A `custom` choice would also be
+    // overridden here, which is intentional: an owner cannot be scoped below
+    // their role on the sync path without the server rejecting their own
+    // writes. Non-owner roles fall through to the grant-based resolution
+    // below — a member/guest's explicit grants ARE their full footprint, and a
+    // (conditionally bypassed) admin stays grant-scoped so a company that set
+    // `admin.viewOthersFiles=false` keeps its admins narrowed.
+    if (m.role === "owner") return { syncMode: "all" };
     // Agent memberships (`agt_…#cmp_…`) belong to an agent identity that owns NO
     // person entity. hq-pro's per-membership sync-config endpoint sits behind an
     // up-front person-gate, so an agent caller is rejected with

package/src/sync/push-event.test.ts

@@ -19,12 +19,14 @@ import {
   decodePushEvent,
   encodePushEvent,
   type PushEvent,
+  type PushEventInput,
 } from "../../src/sync/index.js";
 
 // A canonical, valid PushEvent. All other tests derive from this fixture so
 // any single field mutation can't accidentally pass for the wrong reason.
 const validFixture: PushEvent = {
   relativePath: "docs/architecture/overview.md",
+  kind: "upsert",
   contentHash:
     "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
   mtime: "2026-05-18T12:34:56.789Z",
@@ -34,6 +36,15 @@ const validFixture: PushEvent = {
   eventTimestamp: "2026-05-18T12:35:00.000Z",
 };
 
+const deleteFixture: PushEvent = {
+  relativePath: "docs/architecture/overview.md",
+  kind: "delete",
+  originDeviceId: "device-laptop-a",
+  originTenantId: "tenant-indigo",
+  sequenceNumber: 43,
+  eventTimestamp: "2026-05-18T12:36:00.000Z",
+};
+
 describe("PushEvent encode/decode", () => {
   // ── Acceptance #1: round-trip ──────────────────────────────────────────
   it("round-trips a known-good fixture through encode → decode", () => {
@@ -55,6 +66,21 @@ describe("PushEvent encode/decode", () => {
     expect(fromString).toEqual(validFixture);
   });
 
+  it("round-trips a delete tombstone without contentHash or mtime", () => {
+    const encoded = encodePushEvent(deleteFixture);
+    expect(JSON.parse(encoded)).toEqual(deleteFixture);
+    expect(decodePushEvent(encoded)).toEqual(deleteFixture);
+  });
+
+  it("defaults an absent kind to upsert for backward compatibility", () => {
+    const legacy = { ...validFixture } as PushEventInput;
+    delete legacy.kind;
+
+    const decoded = decodePushEvent(legacy);
+    expect(decoded).toEqual(validFixture);
+    expect(JSON.parse(encodePushEvent(legacy))).toEqual(validFixture);
+  });
+
   // ── Acceptance #2: unknown fields dropped ──────────────────────────────
   it("drops unknown extra fields silently (does not throw)", () => {
     const withExtras = {
@@ -80,8 +106,6 @@ describe("PushEvent encode/decode", () => {
   // ── Acceptance #3: missing required fields throw typed error ───────────
   it.each([
     "relativePath",
-    "contentHash",
-    "mtime",
     "originDeviceId",
     "originTenantId",
     "sequenceNumber",
@@ -106,6 +130,24 @@ describe("PushEvent encode/decode", () => {
     expect(error.issues.some((issue) => issue.path.includes(field))).toBe(true);
   });
 
+  it("rejects an upsert without contentHash and mtime via the schema refinement", () => {
+    let caught: unknown;
+    try {
+      decodePushEvent({
+        ...validFixture,
+        contentHash: undefined,
+        mtime: undefined,
+      });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(PushEventDecodeError);
+    const error = caught as PushEventDecodeError;
+    expect(error.stage).toBe("schema-validation");
+    expect(error.issues.some((issue) => issue.message === "upsert requires contentHash and mtime")).toBe(true);
+  });
+
   it("PushEventDecodeError carries the underlying zod issues array", () => {
     // Multiple missing fields → multiple issues, all reachable via `.issues`.
     const sparse = { relativePath: "x.md" } as unknown;
@@ -117,7 +159,7 @@ describe("PushEvent encode/decode", () => {
     }
     expect(caught).toBeInstanceOf(PushEventDecodeError);
     const error = caught as PushEventDecodeError;
-    expect(error.issues.length).toBeGreaterThanOrEqual(6);
+    expect(error.issues.length).toBeGreaterThanOrEqual(4);
   });
 
   // ── Supporting wire-contract invariants ────────────────────────────────

package/src/sync/push-event.ts

@@ -2,17 +2,20 @@
  * PushEvent — the wire-shared payload exchanged between every link in the
  * event-driven-hq-cloud-sync pipeline.
  *
- * Producers (the watcher) emit one PushEvent per local content change.
+ * Producers (the watcher) emit one PushEvent per local content change or
+ * delete tombstone.
  * Consumers (the push endpoint / receiver / coalescer) decode the payload,
  * validate it, and act on it. Because the same shape crosses a network
  * boundary, it has its own dedicated module.
  *
  * Conventions
  * ───────────
- * - `contentHash` is `sha256:<64-lowercase-hex>`. The `<algorithm>:<hex>`
- *   prefix lets a future hash migration ship without breaking the wire
- *   format — consumers can branch on the prefix and fall back to refusing
- *   unknown algorithms.
+ * - `kind` is `"upsert"` for content changes and `"delete"` for delete
+ *   tombstones. Missing `kind` defaults to `"upsert"` for older producers.
+ * - `contentHash` is required for upserts and absent for delete tombstones.
+ *   It is `sha256:<64-lowercase-hex>`. The `<algorithm>:<hex>` prefix lets a
+ *   future hash migration ship without breaking the wire format — consumers
+ *   can branch on the prefix and fall back to refusing unknown algorithms.
  * - `mtime` and `eventTimestamp` are strict ISO-8601 datetime strings.
  *   `mtime` is the filesystem modification time of the source file at the
  *   moment of capture; `eventTimestamp` is when the watcher emitted the
@@ -59,15 +62,18 @@ export const PushEventSchema = z
     relativePath: z
       .string()
       .min(1, "relativePath must be a non-empty string"),
+    kind: z.enum(["upsert", "delete"]).optional().default("upsert"),
     contentHash: z
       .string()
       .regex(
         CONTENT_HASH_PATTERN,
         "contentHash must match `sha256:<64 lowercase hex>`",
-      ),
+      )
+      .optional(),
     mtime: z
       .string()
-      .regex(ISO8601_DATETIME_PATTERN, "mtime must be an ISO-8601 datetime"),
+      .regex(ISO8601_DATETIME_PATTERN, "mtime must be an ISO-8601 datetime")
+      .optional(),
     originDeviceId: z
       .string()
       .min(1, "originDeviceId must be a non-empty string"),
@@ -91,13 +97,23 @@ export const PushEventSchema = z
   })
   // `.strip()` is the zod 4 default; called explicitly here so the intent is
   // obvious to future readers. Unknown keys MUST NOT throw — see module JSDoc.
-  .strip();
+  .strip()
+  .refine(
+    (e) => e.kind === "delete" || (e.contentHash != null && e.mtime != null),
+    { message: "upsert requires contentHash and mtime" },
+  );
+
+/**
+ * The canonical decoded PushEvent type. `kind` is always present after decode;
+ * `contentHash` and `mtime` are present for upserts and absent for deletes.
+ */
+export type PushEvent = z.output<typeof PushEventSchema>;
 
 /**
- * The canonical PushEvent type. All fields are required; producers and
- * consumers share this exact shape.
+ * Input accepted by the schema. Kept public so encode callers can hand in
+ * legacy upsert payloads where `kind` is absent.
  */
-export type PushEvent = z.infer<typeof PushEventSchema>;
+export type PushEventInput = z.input<typeof PushEventSchema>;
 
 // ─── Errors ────────────────────────────────────────────────────────────────
 
@@ -145,7 +161,7 @@ export class PushEventDecodeError extends Error {
  * Extra keys on `event` are dropped — the returned JSON string contains
  * only the declared PushEvent fields.
  */
-export function encodePushEvent(event: PushEvent): string {
+export function encodePushEvent(event: PushEventInput): string {
   const parsed = PushEventSchema.safeParse(event);
   if (!parsed.success) {
     throw new PushEventDecodeError(

package/src/sync/push-receiver.test.ts

@@ -45,6 +45,7 @@ const QUEUE_URL = "https://sqs.us-east-1.amazonaws.com/123456789012/sync-push-in
 function makeEvent(overrides: Partial<PushEvent> = {}): PushEvent {
   return {
     relativePath: "companies/indigo/notes.md",
+    kind: "upsert",
     contentHash:
       "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
     mtime: "2026-05-21T12:34:56.000Z",