@indigoai-us/hq-cloud 5.32.0 → 5.34.0

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,
+};

package/src/s3.test.ts

@@ -115,12 +115,21 @@ describe("uploadFile", () => {
     fs.writeFileSync(tmpFile, "hello");
   });
 
-  it("omits Metadata when no author is provided (back-compat)", async () => {
+  it("omits author Metadata fields when no author is provided (back-compat)", async () => {
+    // Pre-Bug-#5: this test asserted Metadata was undefined entirely. Now
+    // \`hq-mode\` is stamped on every upload to preserve source-side
+    // permissions, so the assertion is narrower: author fields stay absent
+    // when no author is passed, but \`hq-mode\` is present.
     await uploadFile(makeCtx(), tmpFile, "attribution-test.md");
 
     const put = sentCommands.find((c) => c.name === "PutObjectCommand");
     expect(put).toBeDefined();
-    expect(put!.input.Metadata).toBeUndefined();
+    const meta = put!.input.Metadata as Record<string, string> | undefined;
+    expect(meta?.["created-by"]).toBeUndefined();
+    expect(meta?.["created-by-sub"]).toBeUndefined();
+    expect(meta?.["created-at"]).toBeUndefined();
+    // \`hq-mode\` IS present — that's the new Bug #5 contract.
+    expect(meta?.["hq-mode"]).toMatch(/^[0-7]{3}$/);
   });
 
   it("stamps created-by + created-by-sub + created-at when author is provided", async () => {
@@ -179,6 +188,37 @@ describe("uploadFile", () => {
     expect(Date.now() - stamped).toBeLessThan(60 * 1000);
   });
 
+  it("stamps source file mode as hq-mode metadata (Bug #5 — preserve permissions)", async () => {
+    // Bug #5 (broader than originally reported): every uploaded file's mode
+    // collapsed to the receiver's umask default (0644 on the verification
+    // hosts). 0755 scripts arrived non-executable, breaking every shell-tool
+    // workflow. Fix: stamp the source-side \`mode & 0o777\` into S3 user
+    // metadata as \`hq-mode\` (octal string), then chmod on download.
+    fs.chmodSync(tmpFile, 0o755);
+
+    await uploadFile(makeCtx(), tmpFile, "exec.sh");
+
+    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
+    expect(put).toBeDefined();
+    const meta = put!.input.Metadata as Record<string, string> | undefined;
+    expect(meta?.["hq-mode"]).toBe("755");
+  });
+
+  it("stamps various modes correctly (0600, 0640, 0700, 0750)", async () => {
+    // Verification report V5: all four modes collapsed to 0644 receiver-side
+    // because the upload carried no mode at all. Pin each mode round-trips
+    // through the metadata header in canonical octal-string form (no leading
+    // zero — the parser uses parseInt(..., 8)).
+    for (const mode of [0o600, 0o640, 0o700, 0o750]) {
+      sentCommands.length = 0;
+      fs.chmodSync(tmpFile, mode);
+      await uploadFile(makeCtx(), tmpFile, "f.bin");
+      const put = sentCommands.find((c) => c.name === "PutObjectCommand");
+      const meta = put!.input.Metadata as Record<string, string> | undefined;
+      expect(meta?.["hq-mode"]).toBe(mode.toString(8));
+    }
+  });
+
   it("elides non-ASCII or empty author fields rather than throwing", async () => {
     // S3 user-defined metadata must be ASCII-only and total ≤ 2KB. Partial
     // attribution beats hard failure — values that fail the printable check
@@ -630,6 +670,106 @@ describe("downloadFile", () => {
     expect(fs.readlinkSync(localPath)).toBe("fresh-target.md");
   });
 
+  it("applies hq-mode metadata via chmod after byte write (Bug #5 — preserve permissions)", async () => {
+    // Round-trip pair to the s3.upload test: source-side mode lives in
+    // \`Metadata['hq-mode']\` as an octal string; the receiver must chmod
+    // the file to that exact mode after writing the bytes. Pre-fix the
+    // receiver took the umask default and 0755 scripts arrived 0644.
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new Uint8Array([35, 33, 47, 98, 105, 110]); // "#!/bin"
+      })(),
+      Metadata: { "hq-mode": "755" },
+    };
+
+    const localPath = path.join(tmpRoot, "exec.sh");
+    await downloadFile(makeCtx(), "exec.sh", localPath);
+
+    // mask to permission bits — the upper bits encode file-type (S_IFREG)
+    // and are not preserved on chmod.
+    const stat = fs.statSync(localPath);
+    expect((stat.mode & 0o777).toString(8)).toBe("755");
+  });
+
+  it("rounds-trips multiple modes (0600/0640/0700/0750/0755) via hq-mode", async () => {
+    // Verification report V5 multi-mode pin: every mode collapsed to 0644
+    // because the receiver had no mode signal at all. With \`hq-mode\` in
+    // metadata, all five modes must arrive at their exact source value.
+    for (const octal of ["600", "640", "700", "750", "755"]) {
+      nextGetObjectResponse = {
+        Body: (async function* () {
+          yield new Uint8Array([97]); // "a"
+        })(),
+        Metadata: { "hq-mode": octal },
+      };
+      const localPath = path.join(tmpRoot, `mode-${octal}.bin`);
+      await downloadFile(makeCtx(), `mode-${octal}.bin`, localPath);
+      expect((fs.statSync(localPath).mode & 0o777).toString(8)).toBe(octal);
+    }
+  });
+
+  it("rejects malformed hq-mode metadata via strict-octal regex (Codex P2)", async () => {
+    // Codex review on PR #24 caught: parseInt(modeOctal, 8) accepts
+    // partial-prefix garbage — "755junk" parses to 0o755 instead of
+    // NaN — so tampered or malformed metadata could still chmod the
+    // local file. Strict regex MUST reject anything that isn't pure
+    // octal digits before parseInt sees it; the file then arrives at
+    // umask default like the legacy back-compat path.
+    const malformed = [
+      "755junk", // trailing garbage — parseInt parses 0o755 pre-fix
+      "0x755",   // hex-looking prefix
+      "8",       // out-of-octal-range digit
+      "9",       // ditto
+      "-755",    // signed
+      "abc",     // non-numeric
+      "",        // empty
+      "7777",    // mode > 0o777 after parse
+      "12345",   // too long (more than 4 octal digits)
+      "  755 ",  // whitespace
+    ];
+    for (const bad of malformed) {
+      nextGetObjectResponse = {
+        Body: (async function* () {
+          yield new Uint8Array([116]); // "t"
+        })(),
+        Metadata: { "hq-mode": bad },
+      };
+      const localPath = path.join(tmpRoot, `bad-${malformed.indexOf(bad)}.bin`);
+      await downloadFile(makeCtx(), `bad-${malformed.indexOf(bad)}.bin`, localPath);
+      // Mode MUST be the umask default (whatever the test process inherits),
+      // NOT a partial-parse of the malformed string. Specifically, even if
+      // the malformed string would partial-parse to 0755, the file must NOT
+      // arrive at 0755 — it must take the umask default. We can't pin the
+      // exact default value (test runner umask varies), but we can pin that
+      // a partial-parse value (0o755) does NOT match for "755junk" cases.
+      const mode = (fs.statSync(localPath).mode & 0o777);
+      // Heuristic: if the parsed mode would have been 0o755, fail loudly.
+      // (umask default on most CI runners is 0o644 or 0o664, never 0o755.)
+      if (bad.startsWith("755") || bad === "0x755") {
+        expect(mode).not.toBe(0o755);
+      }
+    }
+  });
+
+  it("downloads with default umask permissions when hq-mode metadata is absent (back-compat)", async () => {
+    // Legacy uploads from pre-fix engines have no \`hq-mode\` metadata.
+    // The receiver must NOT crash and must NOT change the mode — let
+    // the OS default apply, mirroring the pre-fix behavior.
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new Uint8Array([108, 101, 103, 97, 99, 121]); // "legacy"
+      })(),
+      Metadata: {},
+    };
+
+    const localPath = path.join(tmpRoot, "legacy.bin");
+    await expect(
+      downloadFile(makeCtx(), "legacy.bin", localPath),
+    ).resolves.toBeDefined();
+    // No assertion on mode — receiver default is whatever umask set.
+    expect(fs.readFileSync(localPath, "utf-8")).toBe("legacy");
+  });
+
   it("returns the object's user-metadata (including created-by) for a regular file", async () => {
     nextGetObjectResponse = {
       Body: (async function* () {

package/src/s3.ts

@@ -160,6 +160,28 @@ export function decodeSymlinkMetadataValue(value: string): string {
  */
 export 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 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
@@ -178,6 +200,20 @@ export async function uploadFile(
   const client = buildClient(ctx);
   const body = fs.readFileSync(localPath);
 
+  // Capture source-side file mode (permission bits only) for Bug #5 — see
+  // FILE_MODE_META_KEY doc. Best-effort: lstat failure (raced rm, EPERM)
+  // falls through to "no mode header" and the receiver keeps its umask
+  // default — same as the legacy back-compat path.
+  let modeOctal: string | undefined;
+  try {
+    const lstat = fs.lstatSync(localPath);
+    if (!lstat.isSymbolicLink()) {
+      modeOctal = (lstat.mode & 0o777).toString(8);
+    }
+  } catch {
+    // Leave modeOctal undefined; receiver applies its umask default.
+  }
+
   // Preserve the original `created-at` across re-uploads when the object
   // already exists with author metadata — same convention the hq-console
   // upload route uses, so the NEW-pill ageing window doesn't reset on every
@@ -198,7 +234,10 @@ export async function uploadFile(
     }
   }
 
-  const Metadata = author ? buildAuthorMetadata(author, createdAt) : undefined;
+  const Metadata: Record<string, string> = {
+    ...(author ? buildAuthorMetadata(author, createdAt) : {}),
+    ...(modeOctal ? { [FILE_MODE_META_KEY]: modeOctal } : {}),
+  };
 
   const response = await client.send(
     new PutObjectCommand({
@@ -206,7 +245,7 @@ export async function uploadFile(
       Key: key,
       Body: body,
       ContentType: getMimeType(key),
-      ...(Metadata && Object.keys(Metadata).length > 0 ? { Metadata } : {}),
+      ...(Object.keys(Metadata).length > 0 ? { Metadata } : {}),
     }),
   );
 
@@ -404,6 +443,36 @@ export async function downloadFile(
     chunks.push(Buffer.from(chunk));
   }
   fs.writeFileSync(localPath, Buffer.concat(chunks));
+
+  // Bug #5 — apply source-side mode after the byte write. See
+  // FILE_MODE_META_KEY for the metadata contract. Parses defensively:
+  // a malformed value falls through with no chmod so the umask default
+  // applies, matching the legacy back-compat path. fs.chmodSync
+  // follows symlinks — that's fine here because we're on the regular-
+  // file branch (the symlink branch above already returned).
+  //
+  // Codex P2 (PR #24 round 3): strict octal-only regex BEFORE parseInt.
+  // parseInt(modeOctal, 8) accepts partial-prefix garbage — "755junk"
+  // parses to 0o755 instead of NaN — so tampered or malformed metadata
+  // could still change local permissions unexpectedly. The regex
+  // requires 1–4 pure octal digits (`[0-7]{1,4}$`), which matches what
+  // the upload side stamps (`(mode & 0o777).toString(8)` → at most
+  // three digits, all 0–7) and rejects everything else.
+  const modeOctal = response.Metadata?.[FILE_MODE_META_KEY];
+  if (typeof modeOctal === "string" && /^[0-7]{1,4}$/.test(modeOctal)) {
+    const parsed = parseInt(modeOctal, 8);
+    if (Number.isFinite(parsed) && parsed >= 0 && parsed <= 0o777) {
+      try {
+        fs.chmodSync(localPath, parsed);
+      } catch {
+        // chmod failure (read-only FS, EPERM) is non-fatal — the file
+        // is materialized, just with the umask default. Surface via
+        // S3-side metadata being present but the file not matching;
+        // a future operator-side audit can reconcile.
+      }
+    }
+  }
+
   return { metadata: response.Metadata };
 }