@indigoai-us/hq-cloud 5.32.0 → 5.34.0

package/dist/lib/machine-id.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+declare function menubarJsonPath(): string;
+/**
+ * Path to `<hqRoot>/.hq/machine-id` — the source-of-truth file.
+ */
+declare function hqRootMachineIdPath(hqRoot: string): string;
+/**
+ * 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.
+ */
+declare function readHqRootMachineId(hqRoot: string): string | undefined;
+/**
+ * Read the menubar-written id from `~/.hq/menubar.json`, or undefined if
+ * the file is missing / unreadable / doesn't contain a string `machineId`.
+ */
+declare function readMenubarMachineId(): string | 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.
+ */
+declare function persistMachineId(hqRoot: string, id: string): void;
+/**
+ * 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 declare function getOrCreateMachineId(hqRoot: string): string;
+/**
+ * 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 declare function readShortMachineId(hqRoot: string): string;
+/**
+ * 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 declare const _testing: {
+    menubarJsonPath: typeof menubarJsonPath;
+    hqRootMachineIdPath: typeof hqRootMachineIdPath;
+    readHqRootMachineId: typeof readHqRootMachineId;
+    readMenubarMachineId: typeof readMenubarMachineId;
+    persistMachineId: typeof persistMachineId;
+};
+export {};
+//# sourceMappingURL=machine-id.d.ts.map

package/dist/lib/machine-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-id.d.ts","sourceRoot":"","sources":["../../src/lib/machine-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAOH;;;;;GAKG;AACH,iBAAS,eAAe,IAAI,MAAM,CAEjC;AAED;;GAEG;AACH,iBAAS,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;GAIG;AACH,iBAAS,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO/D;AAED;;;GAGG;AACH,iBAAS,oBAAoB,IAAI,MAAM,GAAG,SAAS,CAWlD;AAED;;;;GAIG;AACH,iBAAS,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAQ1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAqB3D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKzD;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ;;;;;;CAMpB,CAAC"}

package/dist/lib/machine-id.js

@@ -0,0 +1,170 @@
+/**
+ * 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() {
+    return path.join(os.homedir(), ".hq", "menubar.json");
+}
+/**
+ * Path to `<hqRoot>/.hq/machine-id` — the source-of-truth file.
+ */
+function hqRootMachineIdPath(hqRoot) {
+    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) {
+    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() {
+    try {
+        const raw = fs.readFileSync(menubarJsonPath(), "utf-8");
+        const parsed = JSON.parse(raw);
+        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, id) {
+    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) {
+    // 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) {
+    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,
+};
+//# sourceMappingURL=machine-id.js.map

package/dist/lib/machine-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-id.js","sourceRoot":"","sources":["../../src/lib/machine-id.ts"],"names":[],"mappings":"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"}

package/dist/lib/machine-id.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=machine-id.test.d.ts.map

package/dist/lib/machine-id.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-id.test.d.ts","sourceRoot":"","sources":["../../src/lib/machine-id.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/lib/machine-id.test.js

@@ -0,0 +1,195 @@
+/**
+ * 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) {
+    return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+describe("getOrCreateMachineId (four-tier resolver)", () => {
+    let originalHome;
+    let originalEnvId;
+    let tmpHome;
+    let tmpHqRoot;
+    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;
+    let originalEnvId;
+    let tmpHome;
+    let tmpHqRoot;
+    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}$/);
+    });
+});
+//# sourceMappingURL=machine-id.test.js.map

package/dist/lib/machine-id.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-id.test.js","sourceRoot":"","sources":["../../src/lib/machine-id.test.ts"],"names":[],"mappings":"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"}

package/dist/s3.d.ts

@@ -87,6 +87,27 @@ export declare function decodeSymlinkMetadataValue(value: string): string;
  * extension can encode additional fields if needed.
  */
 export declare const SYMLINK_BODY_PREFIX = "hq-symlink:";
+/**
+ * S3 user-metadata key carrying the source-side file mode (permission bits
+ * only — \`mode & 0o777\`) as an octal string ("755", "640", etc.). On
+ * download, downloadFile parses this with \`parseInt(value, 8)\` and chmods
+ * the file to the exact source mode after the byte write.
+ *
+ * Bug #5 in the 5.33.0 deep-test was originally reported as "exec bit lost
+ * on sync" but the verification report broadened it: ALL modes (0600 / 0640
+ * / 0700 / 0750 / 0755) collapsed to the receiver's umask default (0644)
+ * because no mode signal crossed the wire at all. Stamping the mode in
+ * metadata is the smallest schema change that preserves the full
+ * permission bitfield without a per-host umask negotiation.
+ *
+ * Symlinks: skipped at upload time (symlink mode is OS-controlled
+ * lrwxrwxrwx) and skipped on download (\`fs.chmodSync\` follows symlinks
+ * and would mutate the target's mode instead).
+ *
+ * Back-compat: legacy uploads have no \`hq-mode\` header — the receiver
+ * leaves the umask default in place, matching pre-fix behavior.
+ */
+export declare const FILE_MODE_META_KEY = "hq-mode";
 /**
  * Encode/decode the symlink wire body. Kept as exported helpers so the
  * format is centrally defined and tests can probe both sides without

package/dist/s3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../src/s3.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAkBhD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf;AA6BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AAEjD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,aAAa,EAClB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAqC3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA+C3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,CAiHhD;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,eAAe,CACnC,GAAG,EAAE,aAAa,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,EAAE,CAAC,CAwDvB;AAED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,YAAY,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CAAC,CAqBvG"}
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../src/s3.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAkBhD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf;AA6BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,aAAa,EAClB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAsD3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA+C3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,CA+IhD;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,eAAe,CACnC,GAAG,EAAE,aAAa,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,EAAE,CAAC,CAwDvB;AAED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,YAAY,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CAAC,CAqBvG"}