@indigoai-us/hq-cloud 5.32.0 → 5.33.0

package/src/cli/share.test.ts

@@ -2454,6 +2454,23 @@ describe("isEphemeralPath (conflict-mirror pattern contract)", () => {
     ["foo.conflict-2026-05-19T17-05-56Z-deadbeef.md", true],
     // Non-markdown extensions also valid (sh scripts, ts files, etc.).
     ["foo.sh.conflict-2026-05-19T17-05-56Z-abc123.sh", true],
+    // ── extensionless originals (regression: `path.extname('.gitignore')`
+    //    returns '' in Node, so `buildConflictPath` produces no trailing
+    //    `.<ext>` segment for hidden-but-extensionless files).
+    [".gitignore.conflict-2026-05-23T19-51-38Z-4dff71", true],
+    [".hqignore.conflict-2026-05-23T19-51-38Z-4dff71", true],
+    [".agents/skills.conflict-2026-05-19T17-07-01Z-0a513b", true],
+    // ── legacy "unknown" machine token (regression: hosts without
+    //    `~/.hq/menubar.json` pre-Fix-3 fell through to the literal string
+    //    `"unknown"`, which `[a-f0-9]+` refused. Producer side is closed in
+    //    `../lib/machine-id.ts`, but the regex still must filter the
+    //    already-on-disk legacy files so the next push removes them).
+    [".gitignore.conflict-2026-05-15T15-10-35Z-unknown", true],
+    [".agents/skills.conflict-2026-05-15T15-10-35Z-unknown", true],
+    ["notes.md.conflict-2026-05-15T15-10-35Z-unknown.md", true],
+    [".hq/install-manifest.json.conflict-2026-05-15T15-11-58Z-unknown.json", true],
+    // Multi-dot extension (e.g., archive tarballs that conflicted).
+    ["dump.conflict-2026-05-13T19-40-40Z-abc.tar.gz", true],
   ])("matches conflict mirror: %s", (p, expected) => {
     expect(isEphemeralPath(p)).toBe(expected);
   });
@@ -2467,17 +2484,20 @@ describe("isEphemeralPath (conflict-mirror pattern contract)", () => {
     ["conflict-resolution.md", false],
     ["my-conflict.md", false],
     ["foo.conflict-handler.md", false],
-    // Date-shaped but missing the trailing dot + extension (real conflicts
-    // always carry a file extension; the trailing `\.` in the pattern is the
-    // safety against bare-substring false positives).
-    ["foo.conflict-2026-05-13T19-40-40Z-abc", false],
-    // Wrong-case or non-hex machine hash.
+    // Wrong-case or non-hex/non-"unknown" machine hash.
     ["foo.conflict-2026-05-13T19-40-40Z-ZZZZZZ.md", false],
     // Wrong timestamp format (real conflicts use UTC ISO with Z suffix).
     ["foo.conflict-2026-05-13-abc123.md", false],
-    // Missing leading dot before "conflict" (this protects against legitimate
+    // Missing leading dot before "conflict" (protects against legitimate
     // files that happen to contain the word "conflict" mid-name).
     ["fooconflict-2026-05-13T19-40-40Z-abc.md", false],
+    // Extra trailing segments after the machine hash — the `$` anchor +
+    // `[^/]*` ext class ensure a conflict marker can't appear mid-path.
+    ["foo.conflict-2026-05-13T19-40-40Z-abc/extra/path", false],
+    ["foo.conflict-2026-05-13T19-40-40Z-abc-then-more-text", false],
+    // Bare "unknown"-like tokens that aren't the literal sentinel.
+    ["foo.conflict-2026-05-13T19-40-40Z-unknowing.md", false],
+    ["foo.conflict-2026-05-13T19-40-40Z-UNKNOWN.md", false],
   ])("rejects non-mirror: %s", (p, expected) => {
     expect(isEphemeralPath(p)).toBe(expected);
   });

package/src/cli/share.ts

@@ -32,8 +32,11 @@ import type { SyncProgressEvent } from "./sync.js";
 /**
  * Local-only ephemeral artifacts: conflict-mirror files written by the pull
  * leg whenever a 3-way merge keeps local AND wants to preserve the remote
- * version for inspection. Format: `<orig>.conflict-<ISO-utc>-<machineHash>.<ext>`
- * (e.g. `.claude/CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md`).
+ * version for inspection. Format: `<orig>.conflict-<ISO-utc>-<machineHash>[.ext]`
+ * (e.g. `.claude/CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md`,
+ * or `.gitignore.conflict-2026-05-13T19-40-40Z-e5797a` — extensionless
+ * originals produce no trailing dot, see `buildConflictPath` in
+ * `../lib/conflict-file.ts`).
  *
  * These files MUST never round-trip to S3 — they're local-only safety backups
  * the user reviews and deletes once the merge is resolved. Pre-fix, the push
@@ -42,13 +45,34 @@ import type { SyncProgressEvent } from "./sync.js";
  * deleted them locally (because pull-confirmation had stamped them as
  * `direction: "down"`). Net effect: a permanent litter ratchet on remote.
  *
+ * Two known producer-shapes the regex must accommodate (both observed on
+ * affected user trees prior to this fix):
+ *
+ *   1. **`unknown` machine token.** Pre-`<hqRoot>/.hq/machine-id`
+ *      provisioning (see `../lib/machine-id.ts`), hosts without
+ *      `~/.hq/menubar.json` — every Linux HQ Pro Outpost, every fresh CLI
+ *      install — fell through to the literal string `"unknown"` from the
+ *      old `readShortMachineId()` fallback. The letters `k`, `n`, `o`, `w`
+ *      live outside `[a-f]`, so the pre-fix `[a-f0-9]+` class refused those
+ *      filenames. They round-tripped to S3 as ordinary files (which IS the
+ *      "permanent litter ratchet" this module's contract was supposed to
+ *      prevent). The new machine-id provisioning closes the producer side,
+ *      but we still accept `unknown` here so legacy files already on disk
+ *      are filtered out by the next push.
+ *
+ *   2. **Extensionless originals.** `path.extname('.gitignore')` returns
+ *      `''` in Node, so `buildConflictPath` produces no trailing `.<ext>`
+ *      segment for hidden-but-extensionless files like `.gitignore`,
+ *      `.hqignore`, or any `.agents/skills`-style entry. The pre-fix `\.`
+ *      tail was mandatory, so those names slipped through.
+ *
  * Wire-points: (1) push walker — `collectFiles` / `walkDir` skip these so
  * they never upload; (2) `computeDeletePlan` — skip these so an already-
  * journaled mirror that's been deleted locally doesn't get included in the
  * regular delete plan (the dedicated reconcile path handles existing litter).
  */
 const EPHEMERAL_PATH_PATTERN =
-  /\.conflict-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z-[a-f0-9]+\./;
+  /\.conflict-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z-(?:[a-f0-9]+|unknown)(?:\.[^/]*)?$/;
 
 /**
  * Cheap pure check — pass the relative key OR a basename; either works. Used

package/src/cli/sync.ts

@@ -365,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,

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/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}$/);
+  });
+});

package/src/lib/machine-id.ts

@@ -0,0 +1,175 @@
+/**
+ * Machine-ID provisioning — owns the per-host identity used to attribute
+ * conflict mirrors, telemetry rows, and `.hq-conflicts/index.json` entries.
+ *
+ * Historically the menubar app (`indigoai-us/hq-sync`) was the sole writer
+ * of `machineId` via `~/.hq/menubar.json`, and every other sync caller
+ * best-effort read from there. That arrangement is backwards: hq-cloud is
+ * the engine that runs on every sync host (macOS-with-menubar, macOS CLI,
+ * Linux HQ Pro Outposts, future Windows), while the menubar is an optional
+ * macOS-only UI. Linux outposts therefore had no menubar.json, so
+ * `readShortMachineId()` returned the literal string `"unknown"` and
+ * every conflict file on those hosts was tagged `-unknown` (which then
+ * also slipped past `EPHEMERAL_PATH_PATTERN` in `src/cli/share.ts` — see
+ * Fix 2 — and rode S3 round-trips as a regular file).
+ *
+ * This module flips ownership: hq-cloud provisions a UUID on first call
+ * and persists it to `<hqRoot>/.hq/machine-id` (one line, plain text).
+ * Every subsequent call hits the persisted file. Existing macOS installs
+ * with menubar-written IDs are migrated forward on first call: tier 3
+ * picks up the menubar.json value, writes it to `<hqRoot>/.hq/machine-id`,
+ * and returns it — so the id is stable across the migration window.
+ *
+ * Resolution order (first hit wins, every miss falls through):
+ *   1. `process.env.HQ_MACHINE_ID` — explicit override for CI / tests.
+ *   2. `<hqRoot>/.hq/machine-id` — source-of-truth on the host.
+ *   3. `~/.hq/menubar.json` `machineId` field — back-compat for existing
+ *      macOS installs; migrated forward to tier 2 on first read.
+ *   4. Autogen — write a fresh UUID to `<hqRoot>/.hq/machine-id` and return.
+ *
+ * Concurrent autogen race is benign: two writers each pick a fresh UUID,
+ * last-writer-wins on disk, both processes re-read the now-stable file on
+ * their next call. The window is narrow (single sync run startup) and the
+ * downside (one extra conflict-file rename across a single race window) is
+ * trivial compared to the litter-ratchet bug it replaces.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/**
+ * Path to `~/.hq/menubar.json`. Evaluated lazily at call time (not module
+ * load) so tests overriding `HOME` post-import 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");
+}
+
+/**
+ * Path to `<hqRoot>/.hq/machine-id` — the source-of-truth file.
+ */
+function hqRootMachineIdPath(hqRoot: string): string {
+  return path.join(hqRoot, ".hq", "machine-id");
+}
+
+/**
+ * Read the persisted id from `<hqRoot>/.hq/machine-id`, or undefined if
+ * absent/unreadable/empty. Trims trailing whitespace so manual edits with
+ * a final newline don't break attribution.
+ */
+function readHqRootMachineId(hqRoot: string): string | undefined {
+  try {
+    const raw = fs.readFileSync(hqRootMachineIdPath(hqRoot), "utf-8").trim();
+    return raw.length > 0 ? raw : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Read the menubar-written id from `~/.hq/menubar.json`, or undefined if
+ * the file is missing / unreadable / doesn't contain a string `machineId`.
+ */
+function readMenubarMachineId(): string | undefined {
+  try {
+    const raw = fs.readFileSync(menubarJsonPath(), "utf-8");
+    const parsed = JSON.parse(raw) as { machineId?: unknown };
+    if (typeof parsed.machineId === "string" && parsed.machineId.length > 0) {
+      return parsed.machineId;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Persist `id` to `<hqRoot>/.hq/machine-id`. Best-effort — failures are
+ * silent so a read-only hqRoot (e.g. a CI mount) still gets a working id
+ * for the current process, even if it can't be persisted for the next run.
+ */
+function persistMachineId(hqRoot: string, id: string): void {
+  try {
+    fs.mkdirSync(path.join(hqRoot, ".hq"), { recursive: true });
+    fs.writeFileSync(hqRootMachineIdPath(hqRoot), `${id}\n`);
+  } catch {
+    // Read-only filesystem or permission issue — caller gets the id back
+    // anyway. Next sync run will retry the persist.
+  }
+}
+
+/**
+ * Resolve or provision the machine id for this host, persisting it to
+ * `<hqRoot>/.hq/machine-id` so the result is stable across sync runs.
+ *
+ * Returns the full id (UUID-shaped on first generation, free-form when
+ * migrated from a menubar.json that wrote something non-UUID). Use
+ * {@link readShortMachineId} for the 6-char prefix used in conflict
+ * filenames.
+ */
+export function getOrCreateMachineId(hqRoot: string): string {
+  // Tier 1: env override.
+  const fromEnv = process.env.HQ_MACHINE_ID;
+  if (fromEnv && fromEnv.length > 0) return fromEnv;
+
+  // Tier 2: persisted source-of-truth.
+  const persisted = readHqRootMachineId(hqRoot);
+  if (persisted) return persisted;
+
+  // Tier 3: back-compat read of menubar.json. Migrate forward on first hit
+  // so subsequent calls take tier 2 and the menubar dependency drops out.
+  const fromMenubar = readMenubarMachineId();
+  if (fromMenubar) {
+    persistMachineId(hqRoot, fromMenubar);
+    return fromMenubar;
+  }
+
+  // Tier 4: autogen + persist.
+  const fresh = randomUUID();
+  persistMachineId(hqRoot, fresh);
+  return fresh;
+}
+
+/**
+ * Short form (six hex chars) for use in conflict filenames. The short
+ * token is what gets stamped into `<orig>.conflict-<ts>-<short>.<ext>` —
+ * see `buildConflictPath` in `./conflict-file.ts`.
+ *
+ * **Always returns `[a-f0-9]{6}`** so the resulting filename matches the
+ * `EPHEMERAL_PATH_PATTERN` in `src/cli/share.ts`. Tier 1 (`HQ_MACHINE_ID`)
+ * and tier 3 (legacy menubar values) can return arbitrary non-hex strings
+ * — e.g. an env override of `"ci-runner-42"` or a menubar-written
+ * `"menubar-legacy-id"`. Slicing those raw would produce `ci-run` or
+ * `menuba`, which the ephemeral filter would refuse and the push walker
+ * would round-trip to S3 — the exact litter-ratchet bug this module
+ * exists to close.
+ *
+ * Normalization: if the first 6 chars of the resolved id are all hex
+ * (the typical UUID / hex-id case), use them as-is so the short token
+ * remains an intuitive prefix of the full id. Otherwise derive a
+ * deterministic SHA-1 hash of the full id and take the first 6 chars —
+ * stable across calls, attributable to the same machine, always hex.
+ */
+export function readShortMachineId(hqRoot: string): string {
+  const full = getOrCreateMachineId(hqRoot);
+  const head = full.slice(0, 6);
+  if (/^[a-f0-9]{6}$/.test(head)) return head;
+  return createHash("sha1").update(full).digest("hex").slice(0, 6);
+}
+
+/**
+ * Test-only exports. Mirrors the `_testing` namespace pattern used by
+ * `src/cli/share.ts` so regression-critical helpers can be pinned by
+ * direct unit tests without round-tripping through the public API.
+ */
+export const _testing = {
+  menubarJsonPath,
+  hqRootMachineIdPath,
+  readHqRootMachineId,
+  readMenubarMachineId,
+  persistMachineId,
+};