@indigoai-us/hq-cloud 5.31.0 → 5.33.0

package/src/cli/sync.ts

@@ -182,10 +182,36 @@ export interface SyncOptions {
   /**
    * When true, the caller is syncing against the caller's person-entity
    * bucket. Pulled keys whose path starts with `companies/` are dropped
-   * (belt-and-braces — the person bucket should never contain those,
-   * but the runner must not write them into the user's company folders).
+   * by default (belt-and-braces — the person bucket should never contain
+   * those, and the runner must not write them into the user's company
+   * folders). See `includeLocalCompanies` for the opt-in escape hatch.
    */
   personalMode?: boolean;
+  /**
+   * Opt-in: when `personalMode === true`, allow `companies/{slug}/...` keys
+   * through the pull filter EXCEPT for slugs in `teamSyncedSlugs` (which
+   * are orphan remnants from a company that was promoted to its own team
+   * bucket and remain pre-decommission). Mirrors the push-side
+   * `HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL=1` gate: when an operator opts
+   * into the cloud:false → personal-bucket fallback on their machine,
+   * pull must also know about the new key shape on the OTHER machine that
+   * subscribes to those keys. Without this, the feature is push-only —
+   * the destination machine never sees the keys.
+   *
+   * Default false preserves the pre-5.20 behavior (drop all
+   * `companies/...` keys in personalMode).
+   */
+  includeLocalCompanies?: boolean;
+  /**
+   * Slugs of companies the operator has an active team-bucket Membership
+   * for. Only consulted when `personalMode === true` AND
+   * `includeLocalCompanies === true`: keys under `companies/{slug}/...`
+   * for any slug in this set are dropped as orphans from a pre-promotion
+   * personal-bucket fallback. The push-side decommission cycle eventually
+   * removes these from the bucket; this filter prevents them from
+   * re-downloading into the same disk paths the team-bucket pull manages.
+   */
+  teamSyncedSlugs?: ReadonlySet<string>;
   /**
    * Override for the per-slug journal file name. Defaults to `ctx.slug`.
    * sync-runner passes `journalSlug: "personal"` for the personal slot so
@@ -267,6 +293,8 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     companyRoot,
     shouldSync,
     options.personalMode === true,
+    options.includeLocalCompanies === true,
+    options.teamSyncedSlugs ?? null,
   );
 
   emit({
@@ -337,7 +365,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
       if (resolution !== "abort" && resolution !== "overwrite") {
         try {
           const detectedAt = new Date().toISOString();
-          const machineId = readShortMachineId();
+          const machineId = readShortMachineId(hqRoot);
           const originalRelative = path.relative(hqRoot, localPath);
           const conflictRelative = buildConflictPath(
             originalRelative,
@@ -613,6 +641,8 @@ function computePullPlan(
   companyRoot: string,
   shouldSync: (filePath: string, isDir?: boolean) => boolean,
   personalMode: boolean,
+  includeLocalCompanies: boolean,
+  teamSyncedSlugs: ReadonlySet<string> | null,
 ): PullPlan {
   const items: PullPlanItem[] = [];
 
@@ -620,8 +650,30 @@ function computePullPlan(
     const localPath = path.join(companyRoot, remoteFile.key);
 
     if (personalMode && remoteFile.key.startsWith("companies/")) {
-      items.push({ action: "skip-personal-mode", remoteFile, localPath });
-      continue;
+      // Default: drop every `companies/...` key — the legacy contract
+      // is that the personal bucket should never contain them.
+      //
+      // EXCEPTION: when the operator has opted into the cloud:false →
+      // personal-bucket fallback (HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL=1
+      // on this machine), keys under `companies/{slug}/...` are
+      // legitimate — they're content a peer machine pushed for a
+      // company whose `company.yaml` declares `cloud: false`. Allow
+      // them through EXCEPT for slugs the operator has an active team-
+      // bucket Membership for: those are orphan remnants from before
+      // the company was promoted, and downloading them would clash
+      // with the team-bucket pull at the same disk path.
+      //
+      // Symmetric to the push-side `decommissionPrefixes` logic in
+      // share.ts — both target the same orphan class, both honor the
+      // same `teamSyncedSlugs` set derived from the operator's live
+      // membership at runtime.
+      const slug = remoteFile.key.split("/")[1] ?? "";
+      const isTeamSyncedOrphan =
+        teamSyncedSlugs !== null && slug !== "" && teamSyncedSlugs.has(slug);
+      if (!includeLocalCompanies || isTeamSyncedOrphan) {
+        items.push({ action: "skip-personal-mode", remoteFile, localPath });
+        continue;
+      }
     }
 
     // LIST gives us no kind signal for the remote object — we don't

package/src/index.ts

@@ -105,8 +105,11 @@ export type { CognitoAuthConfig, CognitoTokens } from "./cognito-auth.js";
 // Personal-vault scope helpers — shared between hq-sync-runner and `hq sync`
 export {
   PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
+  PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS,
   computePersonalVaultPaths,
+  computePersonalCompanySubdirs,
 } from "./personal-vault.js";
+export type { PersonalVaultOptions } from "./personal-vault.js";
 
 // Personal-vault default-exclusions (5.25+) — second-tier deep-walk filter
 // for secrets, machine-local state, scratch dirs, OS/build cruft.

package/src/lib/conflict-file.ts

@@ -7,38 +7,18 @@
  * surface their own conflicts without name collisions, and lets the user
  * (or the `/resolve-conflicts` HQ skill) see local + cloud side-by-side
  * in their file browser.
+ *
+ * Machine-id provisioning lives in `./machine-id.ts` — hq-cloud owns the
+ * source-of-truth file `<hqRoot>/.hq/machine-id` so every sync host
+ * (including Linux outposts with no menubar app) gets a stable id. This
+ * module re-exports `readShortMachineId` for back-compat with existing
+ * callers; new callers should import directly from `./machine-id.js`.
  */
 
 import * as fs from "fs";
-import * as os from "os";
 import * as path from "path";
 
-/**
- * Path to `~/.hq/menubar.json`. Evaluated lazily at call time (not module
- * load) so that tests overriding `HOME` after import — and any future code
- * that changes the user's effective home dir at runtime — see the right
- * file. Going through `os.homedir()` rather than `process.env.HOME` keeps
- * the Windows USERPROFILE fallback intact.
- */
-function menubarJsonPath(): string {
-  return path.join(os.homedir(), ".hq", "menubar.json");
-}
-
-/**
- * Read the short machine ID (first 6 chars) from `~/.hq/menubar.json`.
- * Falls back to "unknown" if the file is missing/unreadable — conflict
- * files should still be written even when machine identity is unclear.
- */
-export function readShortMachineId(): string {
-  try {
-    const raw = fs.readFileSync(menubarJsonPath(), "utf-8");
-    const parsed = JSON.parse(raw);
-    const id = typeof parsed.machineId === "string" ? parsed.machineId : "";
-    return id.slice(0, 6) || "unknown";
-  } catch {
-    return "unknown";
-  }
-}
+export { readShortMachineId, getOrCreateMachineId } from "./machine-id.js";
 
 /**
  * Build the conflict file path for an original. ISO uses `-` instead of

package/src/lib/conflict.test.ts

@@ -1,7 +1,8 @@
 /**
- * Tests for the pure conflict primitives — path building, machine-id
- * fallback, atomic index writes, dedup. Kept in one file so the related
- * helpers stay co-located.
+ * Tests for the pure conflict primitives — path building, atomic index
+ * writes, dedup. The machine-id resolver moved to `./machine-id.ts` (see
+ * `./machine-id.test.ts`) when hq-cloud took ownership of the provisioning
+ * step from the menubar app.
  */
 
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
@@ -11,7 +12,6 @@ import * as path from "path";
 import {
   buildConflictPath,
   buildConflictId,
-  readShortMachineId,
 } from "./conflict-file.js";
 import {
   appendConflictEntry,
@@ -56,42 +56,6 @@ describe("buildConflictId", () => {
   });
 });
 
-describe("readShortMachineId", () => {
-  let originalHome: string | undefined;
-  let tmpHome: string;
-
-  beforeEach(() => {
-    originalHome = process.env.HOME;
-    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "hq-machineid-"));
-    process.env.HOME = tmpHome;
-  });
-
-  afterEach(() => {
-    if (originalHome) process.env.HOME = originalHome;
-    else delete process.env.HOME;
-    fs.rmSync(tmpHome, { recursive: true, force: true });
-  });
-
-  it("returns the first 6 chars when menubar.json has a machineId", () => {
-    fs.mkdirSync(path.join(tmpHome, ".hq"), { recursive: true });
-    fs.writeFileSync(
-      path.join(tmpHome, ".hq", "menubar.json"),
-      JSON.stringify({ machineId: "deadbeefcafe1234567890" }),
-    );
-    expect(readShortMachineId()).toBe("deadbe");
-  });
-
-  it("falls back to 'unknown' when menubar.json is missing", () => {
-    expect(readShortMachineId()).toBe("unknown");
-  });
-
-  it("falls back to 'unknown' when menubar.json is malformed", () => {
-    fs.mkdirSync(path.join(tmpHome, ".hq"), { recursive: true });
-    fs.writeFileSync(path.join(tmpHome, ".hq", "menubar.json"), "{not-json");
-    expect(readShortMachineId()).toBe("unknown");
-  });
-});
-
 describe("conflict index", () => {
   let tmpHq: string;
 

package/src/lib/describe-error.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import { describeError } from "./describe-error.js";
+
+describe("describeError", () => {
+  it("returns String(value) for non-Error throws", () => {
+    expect(describeError("plain string")).toBe("plain string");
+    expect(describeError(42)).toBe("42");
+    expect(describeError(null)).toBe("null");
+    expect(describeError(undefined)).toBe("undefined");
+  });
+
+  it("returns just the message for a plain Error (skips generic 'Error' name)", () => {
+    expect(describeError(new Error("acme blew up"))).toBe("acme blew up");
+  });
+
+  it("includes named subclasses (TypeError, RangeError, …)", () => {
+    expect(describeError(new TypeError("nope"))).toBe("TypeError nope");
+  });
+
+  it("surfaces AWS SDK v3 UnknownError with cause chain (the bug this fixes)", () => {
+    const sdkErr = new Error("UnknownError");
+    sdkErr.name = "UnknownError";
+    const dnsErr = new Error(
+      "getaddrinfo ENOTFOUND privy.s3.us-east-1.amazonaws.com",
+    );
+    (dnsErr as Error & { code?: string; syscall?: string; hostname?: string }).code =
+      "ENOTFOUND";
+    (dnsErr as Error & { code?: string; syscall?: string; hostname?: string }).syscall =
+      "getaddrinfo";
+    (dnsErr as Error & { code?: string; syscall?: string; hostname?: string }).hostname =
+      "privy.s3.us-east-1.amazonaws.com";
+    (sdkErr as Error & { cause?: unknown }).cause = dnsErr;
+
+    const msg = describeError(sdkErr);
+    expect(msg).toContain("UnknownError");
+    expect(msg).toContain("cause=ENOTFOUND");
+    expect(msg).toContain("syscall=getaddrinfo");
+    expect(msg).toContain("host=privy.s3.us-east-1.amazonaws.com");
+  });
+
+  it("surfaces $metadata.httpStatusCode when present (AccessDenied, etc.)", () => {
+    const err = new Error("The provided credentials were not authorized.");
+    err.name = "AccessDenied";
+    (err as Error & { $metadata?: { httpStatusCode?: number } }).$metadata = {
+      httpStatusCode: 403,
+    };
+    const msg = describeError(err);
+    expect(msg).toContain("AccessDenied");
+    expect(msg).toContain("http=403");
+    expect(msg).toContain("The provided credentials");
+  });
+
+  it("includes own .code attribute on the top-level error", () => {
+    const err = new Error("connect timeout") as Error & { code?: string };
+    err.code = "ETIMEDOUT";
+    expect(describeError(err)).toContain("code=ETIMEDOUT");
+  });
+
+  it("walks up to 3 cause levels, no further", () => {
+    // top → c1 → c2 → c3 → c4 (5 errors, 4 cause hops). The walk should
+    // surface c1/c2/c3 codes but stop before c4.
+    const c4 = new Error("c4");
+    (c4 as Error & { code?: string }).code = "C4_CODE";
+    const c3 = new Error("c3");
+    (c3 as Error & { code?: string; cause?: unknown }).code = "C3_CODE";
+    (c3 as Error & { cause?: unknown }).cause = c4;
+    const c2 = new Error("c2");
+    (c2 as Error & { code?: string; cause?: unknown }).code = "C2_CODE";
+    (c2 as Error & { cause?: unknown }).cause = c3;
+    const c1 = new Error("c1");
+    (c1 as Error & { code?: string; cause?: unknown }).code = "C1_CODE";
+    (c1 as Error & { cause?: unknown }).cause = c2;
+    const top = new Error("top");
+    (top as Error & { cause?: unknown }).cause = c1;
+    const msg = describeError(top);
+    expect(msg).toContain("cause=C1_CODE");
+    expect(msg).toContain("cause=C2_CODE");
+    expect(msg).toContain("cause=C3_CODE");
+    // c4 is the 4th cause level — outside the 3-level walk
+    expect(msg).not.toContain("C4_CODE");
+  });
+
+  it("breaks on a cycle in the cause chain", () => {
+    const a = new Error("a");
+    const b = new Error("b");
+    (a as Error & { cause?: unknown }).cause = b;
+    (b as Error & { cause?: unknown }).cause = a;
+    // Should not infinite-loop; should return something containing "a" and "b".
+    const msg = describeError(a);
+    expect(msg).toContain("a");
+    expect(msg).toContain("b");
+  });
+
+  it("de-dups consecutive identical fragments (the 'UnknownError UnknownError' case)", () => {
+    const err = new Error("UnknownError");
+    err.name = "UnknownError";
+    // Without de-dup the output would start "UnknownError UnknownError".
+    expect(describeError(err)).toBe("UnknownError");
+  });
+});

package/src/lib/describe-error.ts

@@ -0,0 +1,58 @@
+/**
+ * Surface AWS SDK v3's opaque `UnknownError` wrapper.
+ *
+ * When the SDK can't match a response to a modeled exception (which includes
+ * every Node-side networking failure — `getaddrinfo ENOTFOUND`, `ECONNRESET`,
+ * `EHOSTUNREACH`, expired-DNS-cache hits, etc.) it raises an error whose
+ * `name` and `message` are both literally "UnknownError" and stashes the
+ * underlying Node error on `.cause`. Plain `err.message` extraction at the
+ * catch site loses the cause chain entirely, leaving operators with an
+ * unactionable "UnknownError" in the event stream.
+ *
+ * This walks the cause chain (capped at 3 levels) and stitches together a
+ * single diagnostic line that preserves the original failure mode.
+ *
+ * Example outputs:
+ *   "UnknownError cause=ENOTFOUND syscall=getaddrinfo host=hq-vault-cmp-…s3.us-east-1.amazonaws.com"
+ *   "AccessDenied http=403 The provided credentials …"
+ *   "Error code=ETIMEDOUT cause=ETIMEDOUT host=api.example.com"
+ */
+export function describeError(err: unknown): string {
+  if (!(err instanceof Error)) return String(err);
+
+  const parts: string[] = [];
+  const e = err as Error & {
+    code?: string;
+    $metadata?: { httpStatusCode?: number; requestId?: string };
+    cause?: unknown;
+  };
+
+  if (e.name && e.name !== "Error") parts.push(e.name);
+  if (e.code) parts.push(`code=${e.code}`);
+  if (e.$metadata?.httpStatusCode) parts.push(`http=${e.$metadata.httpStatusCode}`);
+
+  // Walk cause chain to capture the underlying syscall / hostname / code
+  // that the SDK swallowed. Cap depth at 3 and de-cycle with a Set.
+  const seen = new Set<unknown>([err]);
+  let cur: unknown = e.cause;
+  for (let i = 0; i < 3 && cur && !seen.has(cur); i++) {
+    seen.add(cur);
+    const c = cur as {
+      code?: string;
+      syscall?: string;
+      hostname?: string;
+      message?: string;
+      cause?: unknown;
+    };
+    if (c.code) parts.push(`cause=${c.code}`);
+    if (c.syscall) parts.push(`syscall=${c.syscall}`);
+    if (c.hostname) parts.push(`host=${c.hostname}`);
+    if (c.message && c.message !== e.message) parts.push(c.message);
+    cur = c.cause;
+  }
+
+  if (e.message) parts.push(e.message);
+
+  // De-dup consecutive repeats (SDK's "UnknownError UnknownError" case)
+  return parts.filter((p, i) => i === 0 || p !== parts[i - 1]).join(" ");
+}

package/src/lib/machine-id.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Machine-ID resolver tests. Pins the four-tier fallback contract so a
+ * regression in tier ordering, the migration-forward behavior, or the
+ * "unknown sentinel is no longer reachable" invariant is caught at build
+ * time rather than re-litigating it on a user's Lightsail outpost.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { getOrCreateMachineId, readShortMachineId } from "./machine-id.js";
+
+function freshTmp(prefix: string): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+describe("getOrCreateMachineId (four-tier resolver)", () => {
+  let originalHome: string | undefined;
+  let originalEnvId: string | undefined;
+  let tmpHome: string;
+  let tmpHqRoot: string;
+
+  beforeEach(() => {
+    originalHome = process.env.HOME;
+    originalEnvId = process.env.HQ_MACHINE_ID;
+    delete process.env.HQ_MACHINE_ID;
+    tmpHome = freshTmp("hq-machineid-home-");
+    tmpHqRoot = freshTmp("hq-machineid-root-");
+    process.env.HOME = tmpHome;
+  });
+
+  afterEach(() => {
+    if (originalHome) process.env.HOME = originalHome;
+    else delete process.env.HOME;
+    if (originalEnvId !== undefined) process.env.HQ_MACHINE_ID = originalEnvId;
+    else delete process.env.HQ_MACHINE_ID;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+    fs.rmSync(tmpHqRoot, { recursive: true, force: true });
+  });
+
+  // ── tier 1: HQ_MACHINE_ID env override ────────────────────────────────
+  it("tier 1: returns HQ_MACHINE_ID env when set, ignoring lower tiers", () => {
+    process.env.HQ_MACHINE_ID = "env-override-id";
+    // Even if a persisted file exists, env wins.
+    fs.mkdirSync(path.join(tmpHqRoot, ".hq"), { recursive: true });
+    fs.writeFileSync(path.join(tmpHqRoot, ".hq", "machine-id"), "persisted\n");
+    expect(getOrCreateMachineId(tmpHqRoot)).toBe("env-override-id");
+    // Env-only resolution must not clobber the on-disk source-of-truth.
+    expect(fs.readFileSync(path.join(tmpHqRoot, ".hq", "machine-id"), "utf-8").trim()).toBe(
+      "persisted",
+    );
+  });
+
+  // ── tier 2: <hqRoot>/.hq/machine-id ───────────────────────────────────
+  it("tier 2: returns the trimmed contents of <hqRoot>/.hq/machine-id", () => {
+    fs.mkdirSync(path.join(tmpHqRoot, ".hq"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpHqRoot, ".hq", "machine-id"),
+      "  abc-123-persisted  \n\n",
+    );
+    expect(getOrCreateMachineId(tmpHqRoot)).toBe("abc-123-persisted");
+  });
+
+  it("tier 2: empty machine-id file falls through to autogen", () => {
+    fs.mkdirSync(path.join(tmpHqRoot, ".hq"), { recursive: true });
+    fs.writeFileSync(path.join(tmpHqRoot, ".hq", "machine-id"), "");
+    const id = getOrCreateMachineId(tmpHqRoot);
+    // UUID v4 shape.
+    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+    // Persisted on disk for next call.
+    expect(fs.readFileSync(path.join(tmpHqRoot, ".hq", "machine-id"), "utf-8").trim()).toBe(id);
+  });
+
+  // ── tier 3: ~/.hq/menubar.json (legacy, migrated forward) ─────────────
+  it("tier 3: reads menubar.json AND migrates the value into <hqRoot>/.hq/machine-id", () => {
+    fs.mkdirSync(path.join(tmpHome, ".hq"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpHome, ".hq", "menubar.json"),
+      JSON.stringify({ machineId: "menubar-legacy-id" }),
+    );
+    expect(getOrCreateMachineId(tmpHqRoot)).toBe("menubar-legacy-id");
+    // Migrated forward — subsequent calls now hit tier 2.
+    expect(fs.readFileSync(path.join(tmpHqRoot, ".hq", "machine-id"), "utf-8").trim()).toBe(
+      "menubar-legacy-id",
+    );
+  });
+
+  it("tier 3: malformed menubar.json falls through to autogen", () => {
+    fs.mkdirSync(path.join(tmpHome, ".hq"), { recursive: true });
+    fs.writeFileSync(path.join(tmpHome, ".hq", "menubar.json"), "{not-json");
+    const id = getOrCreateMachineId(tmpHqRoot);
+    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  });
+
+  it("tier 3: menubar.json without a machineId field falls through to autogen", () => {
+    fs.mkdirSync(path.join(tmpHome, ".hq"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpHome, ".hq", "menubar.json"),
+      JSON.stringify({ telemetryEnabled: true }),
+    );
+    const id = getOrCreateMachineId(tmpHqRoot);
+    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  });
+
+  // ── tier 4: autogen + persist ─────────────────────────────────────────
+  it("tier 4: generates a UUID and persists it for the next call", () => {
+    const id = getOrCreateMachineId(tmpHqRoot);
+    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+    expect(fs.readFileSync(path.join(tmpHqRoot, ".hq", "machine-id"), "utf-8").trim()).toBe(id);
+    // Stable across calls.
+    expect(getOrCreateMachineId(tmpHqRoot)).toBe(id);
+  });
+
+  it("tier 4: stays in-process even if hqRoot is read-only (best-effort persist)", () => {
+    // Pre-create .hq as a regular dir, then strip write perms.
+    fs.mkdirSync(path.join(tmpHqRoot, ".hq"), { recursive: true });
+    fs.chmodSync(path.join(tmpHqRoot, ".hq"), 0o500); // r-x only
+    try {
+      const id = getOrCreateMachineId(tmpHqRoot);
+      expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+    } finally {
+      fs.chmodSync(path.join(tmpHqRoot, ".hq"), 0o700);
+    }
+  });
+
+  // ── invariant: "unknown" sentinel is unreachable ──────────────────────
+  it("never returns the legacy 'unknown' sentinel — every host gets a real id", () => {
+    // No env, no persisted file, no menubar.json — pure tier-4 path.
+    const id = getOrCreateMachineId(tmpHqRoot);
+    expect(id).not.toBe("unknown");
+    expect(id.length).toBeGreaterThan(6);
+  });
+});
+
+describe("readShortMachineId", () => {
+  let originalHome: string | undefined;
+  let originalEnvId: string | undefined;
+  let tmpHome: string;
+  let tmpHqRoot: string;
+
+  beforeEach(() => {
+    originalHome = process.env.HOME;
+    originalEnvId = process.env.HQ_MACHINE_ID;
+    delete process.env.HQ_MACHINE_ID;
+    tmpHome = freshTmp("hq-machineid-short-home-");
+    tmpHqRoot = freshTmp("hq-machineid-short-root-");
+    process.env.HOME = tmpHome;
+  });
+
+  afterEach(() => {
+    if (originalHome) process.env.HOME = originalHome;
+    else delete process.env.HOME;
+    if (originalEnvId !== undefined) process.env.HQ_MACHINE_ID = originalEnvId;
+    else delete process.env.HQ_MACHINE_ID;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+    fs.rmSync(tmpHqRoot, { recursive: true, force: true });
+  });
+
+  it("returns the first 6 chars when the resolved id has a hex prefix", () => {
+    process.env.HQ_MACHINE_ID = "deadbeefcafe1234567890";
+    expect(readShortMachineId(tmpHqRoot)).toBe("deadbe");
+  });
+
+  it("returns the first 6 chars of an autogenerated UUID", () => {
+    const short = readShortMachineId(tmpHqRoot);
+    expect(short).toHaveLength(6);
+    expect(short).toMatch(/^[0-9a-f]{6}$/);
+    expect(short).not.toBe("unknow"); // legacy "unknown" prefix — must not reappear
+  });
+
+  it("reads the same hex prefix from <hqRoot>/.hq/machine-id when persisted", () => {
+    fs.mkdirSync(path.join(tmpHqRoot, ".hq"), { recursive: true });
+    fs.writeFileSync(path.join(tmpHqRoot, ".hq", "machine-id"), "abcdef-rest-can-be-anything");
+    expect(readShortMachineId(tmpHqRoot)).toBe("abcdef");
+  });
+
+  // ── normalization invariant: short token is ALWAYS [a-f0-9]{6} ────────
+  //
+  // Regression coverage for the Codex-flagged P2 — without this, a
+  // non-hex `HQ_MACHINE_ID` or legacy menubar value (e.g. "ci-runner-42",
+  // "menubar-legacy-id") would slice to a non-hex 6-char prefix, the
+  // conflict filename would carry that non-hex token, and the
+  // `EPHEMERAL_PATH_PATTERN` in `src/cli/share.ts` (which only accepts
+  // `[a-f0-9]+` or the literal `unknown`) would refuse it, restoring the
+  // exact litter-ratchet loop this module exists to close.
+  it.each([
+    // Tier-1 env override with non-hex characters.
+    ["ci-runner-42"],
+    ["env-override-id"],
+    // Tier-3 legacy menubar value with non-hex characters.
+    ["menubar-legacy-id"],
+    // Mixed-case that contains non-hex letters in the first 6 chars.
+    ["Gabc12-rest"],
+    // First 6 chars are hex but contain uppercase (regex is case-sensitive).
+    ["ABCDEF-rest"],
+  ])("normalizes non-hex source ids to a hex token: %s", (sourceId) => {
+    process.env.HQ_MACHINE_ID = sourceId;
+    const short = readShortMachineId(tmpHqRoot);
+    expect(short).toMatch(/^[a-f0-9]{6}$/);
+    expect(short).toHaveLength(6);
+  });
+
+  it("normalization is deterministic — same source id always yields same short token", () => {
+    process.env.HQ_MACHINE_ID = "menubar-legacy-id";
+    const a = readShortMachineId(tmpHqRoot);
+    const b = readShortMachineId(tmpHqRoot);
+    expect(a).toBe(b);
+    expect(a).toMatch(/^[a-f0-9]{6}$/);
+  });
+
+  it("normalization distinguishes different source ids", () => {
+    process.env.HQ_MACHINE_ID = "menubar-legacy-id";
+    const a = readShortMachineId(tmpHqRoot);
+    process.env.HQ_MACHINE_ID = "ci-runner-42";
+    const b = readShortMachineId(tmpHqRoot);
+    expect(a).not.toBe(b);
+    expect(a).toMatch(/^[a-f0-9]{6}$/);
+    expect(b).toMatch(/^[a-f0-9]{6}$/);
+  });
+});