@indigoai-us/hq-cloud 5.33.0 → 5.34.0

package/src/cli/sync.ts

@@ -17,10 +17,12 @@ import {
   hashFile,
   hashSymlinkTarget,
   updateEntry,
+  removeEntry,
   getEntry,
   normalizeEtag,
 } from "../journal.js";
 import { createIgnoreFilter } from "../ignore.js";
+import { isEphemeralPath } from "./share.js";
 import { resolveConflict } from "./conflict.js";
 import type { ConflictStrategy, ConflictResolution } from "./conflict.js";
 import {
@@ -240,6 +242,26 @@ export interface SyncResult {
   newFiles: Array<{ path: string; bytes: number }>;
   /** Convenience count: `newFiles.length`. */
   newFilesCount: number;
+  /**
+   * Count of remote keys refused at planning time because they matched
+   * `EPHEMERAL_PATH_PATTERN` (conflict-mirror files that must never round-
+   * trip through the bucket). Mirrors `ShareResult.filesExcludedByPolicy`
+   * so push and pull report the same shape. Pre-fix this count was always
+   * 0 on the pull side and legacy `.conflict-*` litter rode every sync —
+   * see Bug #2 in workspace/reports/hq-cloud-5.33.0-deep-test.md.
+   */
+  filesExcludedByPolicy: number;
+  /**
+   * Count of journal-known keys applied as local deletes during this pull
+   * because the remote LIST no longer contains them — the cross-machine
+   * delete-propagation signal that Bug #9 closes. The peer's push leg
+   * removed the object from S3 (`hq sync` push side verified-to-work in
+   * the deep-test addendum), but pre-fix the pull side never enumerated
+   * "what's missing-from-remote-that-was-there-before", so the file
+   * lingered locally forever. Always 0 when no journal-known keys have
+   * disappeared from the remote.
+   */
+  filesTombstoned: number;
 }
 
 /**
@@ -279,6 +301,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
   let bytesDownloaded = 0;
   let filesSkipped = 0;
   let conflicts = 0;
+  let filesTombstoned = 0;
   const conflictPaths: string[] = [];
 
   // List all remote files (IAM session policy filters at the AWS layer)
@@ -322,6 +345,13 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
       filesSkipped++;
       continue;
     }
+    if (item.action === "skip-excluded-policy") {
+      // Policy-excluded items count separately from `filesSkipped` so the
+      // pull result mirrors the push side's `filesExcludedByPolicy`
+      // counter — `filesSkipped` stays a measure of "unchanged on this
+      // run", not a catch-all for everything we didn't download.
+      continue;
+    }
 
     const { remoteFile, localPath } = item;
 
@@ -407,6 +437,11 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
           aborted: true,
           newFiles: plan.newFiles,
           newFilesCount: plan.newFilesCount,
+          filesExcludedByPolicy: plan.filesExcludedByPolicy,
+          // Abort short-circuits before the tombstone loop runs; report
+          // 0 so the field shape stays stable for consumers that
+          // destructure it.
+          filesTombstoned: 0,
         };
       }
       if (resolution === "keep" || resolution === "skip") {
@@ -526,6 +561,108 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
   }
   emit({ type: "new-files", files: enrichedNewFiles });
 
+  // Codex P1 (PR #24 follow-up): scope-gate tombstone candidates with
+  // a per-object HEAD before unlinking. `listRemoteFiles` is STS-scoped
+  // (guest sessions with `allowedPrefixes`, role downgrade, custom
+  // sync-mode prefix sets — see the AccessDenied branch in the download
+  // loop above), so a journal entry's absence from LIST does not prove
+  // the object was deleted; it may simply be invisible to this session.
+  // HEAD each candidate:
+  //   - HEAD returns metadata → object exists → NOT in our LIST scope →
+  //     skip the tombstone (peer didn't delete it; we just can't see it).
+  //   - HEAD returns null (NotFound) → confirmed deleted → tombstone.
+  //   - HEAD throws AccessDenied → can't tell → defensive skip; journal
+  //     stays so next sync (with broader scope) can re-evaluate.
+  //   - HEAD throws transient → defensive skip + emit error.
+  // Bounded concurrency mirrors the new-files attribution pass above.
+  if (plan.tombstones.length > 0) {
+    const HEAD_VERIFY_CONCURRENCY = 5;
+    const verified: string[] = [];
+    for (let i = 0; i < plan.tombstones.length; i += HEAD_VERIFY_CONCURRENCY) {
+      const batch = plan.tombstones.slice(i, i + HEAD_VERIFY_CONCURRENCY);
+      const results = await Promise.all(
+        batch.map(async (key) => {
+          try {
+            const head = await headRemoteFile(ctx, key);
+            return head === null ? key : null;
+          } catch (err) {
+            if (isAccessDenied(err)) return null;
+            emit({
+              type: "error",
+              path: key,
+              message: `tombstone HEAD verify failed (deferring): ${
+                err instanceof Error ? err.message : String(err)
+              }`,
+            });
+            return null;
+          }
+        }),
+      );
+      for (const k of results) {
+        if (k !== null) verified.push(k);
+      }
+    }
+    plan.tombstones = verified;
+  }
+
+  // Bug #9 — apply cross-machine delete propagation. Each tombstone is a
+  // key the journal records as previously synced but the remote LIST no
+  // longer contains. We delete the local file (or symlink, or empty dir
+  // remnant) and drop the journal entry so the next sync's planner stays
+  // converged. Failures are reported but non-fatal — the entry stays in
+  // the journal and the next run retries.
+  for (const key of plan.tombstones) {
+    const localPath = path.join(companyRoot, key);
+    let removedSomething = false;
+    try {
+      const lstat = fs.lstatSync(localPath);
+      if (lstat.isSymbolicLink() || lstat.isFile()) {
+        fs.unlinkSync(localPath);
+        removedSomething = true;
+      } else if (lstat.isDirectory()) {
+        // A dir at a key — likely from a (local-dir, cloud-file) historic
+        // state. Don't recursively rm-rf the operator's dir; just drop
+        // the journal entry so we converge with reality.
+      }
+    } catch (err: unknown) {
+      const code =
+        err && typeof err === "object" && "code" in err
+          ? (err as { code?: string }).code
+          : undefined;
+      // ENOENT → local already gone; safe to drop the journal entry.
+      // Other errors (EACCES/EPERM/EBUSY/etc.) leave the local file in
+      // place — if we dropped the journal entry anyway, the pull side
+      // would forget the peer's delete and a later push could re-upload
+      // the still-present local file, silently undoing the peer's delete.
+      // Surface the error and KEEP the journal entry so the next sync
+      // retries the unlink after the operator fixes the permission.
+      if (code !== "ENOENT") {
+        emit({
+          type: "error",
+          path: key,
+          message: `tombstone unlink failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        });
+        // Skip removeEntry / filesTombstoned / progress event — the
+        // tombstone hasn't actually been honored. Next sync retries.
+        continue;
+      }
+    }
+    removeEntry(journal, key);
+    filesTombstoned++;
+    emit({
+      type: "progress",
+      path: key,
+      bytes: 0,
+      deleted: true,
+      // Suffix differentiates a tombstone from a normal delete in the
+      // tty stream — matches the push-side `defaultConsoleLogger`
+      // tombstone surface in share.ts.
+      message: removedSomething ? "tombstone (cross-machine delete)" : "tombstone (already absent locally)",
+    });
+  }
+
   // Stamp lastSync on every successful run so the menubar's "Last sync · X ago"
   // ticks even when nothing transferred. updateEntry only fires on actual
   // downloads; without this, a no-op sync leaves lastSync at the time of the
@@ -542,6 +679,8 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     aborted: false,
     newFiles: plan.newFiles,
     newFilesCount: plan.newFilesCount,
+    filesExcludedByPolicy: plan.filesExcludedByPolicy,
+    filesTombstoned,
   };
 }
 
@@ -590,6 +729,10 @@ type PullPlanItem =
   | { action: "skip-personal-mode"; remoteFile: RemoteFile; localPath: string }
   | { action: "skip-unchanged"; remoteFile: RemoteFile; localPath: string }
   | { action: "skip-local-only"; remoteFile: RemoteFile; localPath: string }
+  // Remote keys refused by ephemeral-mirror policy. The push walker has
+  // refused to upload these since 5.33.0; the pull walker now refuses to
+  // download them so legacy litter in cloud staging drains naturally.
+  | { action: "skip-excluded-policy"; remoteFile: RemoteFile; localPath: string }
   | {
       action: "conflict";
       remoteFile: RemoteFile;
@@ -622,6 +765,15 @@ interface PullPlan {
   /** Files classified as new (no local counterpart at classification time). */
   newFiles: Array<{ path: string; bytes: number }>;
   newFilesCount: number;
+  /** Count of remote keys refused by ephemeral-mirror policy. */
+  filesExcludedByPolicy: number;
+  /**
+   * Journal-known keys missing from the remote LIST. The executor will
+   * apply each as a local delete (file or symlink) + journal removal,
+   * propagating the peer's push-side delete cross-machine (Bug #9).
+   * Carried on the plan so the executor can iterate without re-walking.
+   */
+  tombstones: string[];
 }
 
 /**
@@ -649,6 +801,17 @@ function computePullPlan(
   for (const remoteFile of remoteFiles) {
     const localPath = path.join(companyRoot, remoteFile.key);
 
+    // Ephemeral-mirror filter — symmetric with the push-side walker. Bug #2
+    // in the 5.33.0 deep-test: the push side has refused to upload conflict
+    // mirrors since 5.33.0, but the pull side downloaded them freely from
+    // staging, so legacy `.conflict-*` litter rode every sync into clean
+    // trees. Refuse them here; the V2 verification test (direct S3 inject
+    // bypassing the push filter entirely) is the regression contract.
+    if (isEphemeralPath(remoteFile.key)) {
+      items.push({ action: "skip-excluded-policy", remoteFile, localPath });
+      continue;
+    }
+
     if (personalMode && remoteFile.key.startsWith("companies/")) {
       // Default: drop every `companies/...` key — the legacy contract
       // is that the personal bucket should never contain them.
@@ -705,21 +868,47 @@ function computePullPlan(
     //      dangling link on every run.
     //   3. A regular file: indistinguishable from current behaviour.
     let localLstat: fs.Stats | null = null;
+    let localPathBlockedByFileAncestor = false;
     try {
       localLstat = fs.lstatSync(localPath);
     } catch (err: unknown) {
-      // ENOENT means truly absent; other errors propagate.
-      if (
-        err &&
-        typeof err === "object" &&
-        "code" in err &&
-        (err as { code?: string }).code !== "ENOENT"
-      ) {
+      const code =
+        err && typeof err === "object" && "code" in err
+          ? (err as { code?: string }).code
+          : undefined;
+      // ENOENT  → truly absent → treated as "new file from cloud".
+      // ENOTDIR → an ancestor of localPath is a regular file (cloud has a
+      //           dir at that key, local has a file). Pre-fix this threw
+      //           and aborted the whole company sync (Bug #10 in the
+      //           5.33.0 deep-test verification — \`v4-dir-vs-file\` repro
+      //           wedged the personal company at \"errored\" status,
+      //           skipping every later file). Recover by classifying as
+      //           a structural collision the operator must resolve
+      //           manually, and let the rest of the company process.
+      if (code !== "ENOENT" && code !== "ENOTDIR") {
         throw err;
       }
+      if (code === "ENOTDIR") {
+        localPathBlockedByFileAncestor = true;
+      }
     }
     const localExists = localLstat !== null;
 
+    if (localPathBlockedByFileAncestor) {
+      // Symmetric counterpart to the (local-dir, cloud-file) warning below.
+      // Emit the same "manual reconciliation required" surface so the
+      // operator sees one consistent message for both topologies; record as
+      // skip-local-only so the file is not silently dropped from the
+      // count and the executor never tries to lstat/write it.
+      console.error(
+        `  Warning: an ancestor of ${remoteFile.key} exists locally as a regular file; ` +
+          `cloud has a deeper key under that path. Skipping; manual ` +
+          `reconciliation required (rm the conflicting local file to pull).`,
+      );
+      items.push({ action: "skip-local-only", remoteFile, localPath });
+      continue;
+    }
+
     if (localExists) {
       const isLocalSymlink = localLstat!.isSymbolicLink();
       // Kind-mismatch guard: a remote LIST entry is always a single
@@ -788,6 +977,7 @@ function computePullPlan(
   let bytesToDownload = 0;
   let filesToSkip = 0;
   let filesToConflict = 0;
+  let filesExcludedByPolicy = 0;
   const newFiles: Array<{ path: string; bytes: number }> = [];
   for (const item of items) {
     if (item.action === "download") {
@@ -798,11 +988,106 @@ function computePullPlan(
       }
     } else if (item.action === "conflict") {
       filesToConflict++;
+    } else if (item.action === "skip-excluded-policy") {
+      filesExcludedByPolicy++;
+      // Excluded-policy items don't roll into filesToSkip — they're a
+      // distinct class surfaced via filesExcludedByPolicy so consumers
+      // can render a "N refused by policy" line independently of the
+      // generic "N unchanged" tally.
     } else {
       filesToSkip++;
     }
   }
 
+  // Bug #9 — cross-machine delete propagation. The peer's push leg
+  // already removed the file from S3 (verified in the deep-test
+  // addendum: `aws s3 ls` showed the keys absent post-push). Pre-fix
+  // the pull side enumerated remote keys and downloaded anything
+  // missing locally, but never enumerated "what's missing-from-remote-
+  // that-was-there-before" — so the file stayed forever on every
+  // receiver and `filesTombstoned: 0` showed up on every pull.
+  //
+  // Closing the loop: walk the journal, find every entry whose key is
+  // NOT in the remote LIST set, AND whose path passes the current
+  // ignore filter (paths newly excluded by .hqignore must not trigger
+  // mass-delete), AND — in personalMode — survives the same companies/*
+  // gating the download branch applies. The executor will apply each
+  // as a local delete + journal removal. Symmetric to the push side's
+  // `propagateDeletes` plan in share.ts.
+  const remoteKeySet = new Set<string>();
+  for (const rf of remoteFiles) remoteKeySet.add(rf.key);
+  const tombstones: string[] = [];
+  for (const key of Object.keys(journal.files)) {
+    if (remoteKeySet.has(key)) continue;
+    // PersonalMode key gating — mirror the download branch.
+    if (personalMode && key.startsWith("companies/")) {
+      const slug = key.split("/")[1] ?? "";
+      const isTeamSyncedOrphan =
+        teamSyncedSlugs !== null && slug !== "" && teamSyncedSlugs.has(slug);
+      if (!includeLocalCompanies || isTeamSyncedOrphan) continue;
+    }
+    // Ephemeral keys are filtered both directions; never tombstone-
+    // propagate a conflict-mirror.
+    if (isEphemeralPath(key)) continue;
+    // Honor the current ignore filter — if a path was previously synced
+    // but is now ignored (operator edited .hqignore), do NOT delete
+    // the local copy. They're keeping it deliberately.
+    const localPath = path.join(companyRoot, key);
+    if (!shouldSync(localPath, false) && !shouldSync(localPath, true)) continue;
+    // Codex P1 (PR #24 round 3): detect local edits before tombstoning.
+    // Delete-vs-local-edit race: peer deleted the file remotely while
+    // this machine edited it locally before the next sync. Without
+    // this check, the tombstone executor would unlink the locally-
+    // edited file and drop the journal entry, silently destroying the
+    // user's unsynced work. Compare local hash against the journal
+    // baseline; if they diverge, defer the tombstone. The next pull
+    // run after the operator resolves (re-pushes / overwrites) the
+    // local state will re-evaluate.
+    try {
+      const lstat = fs.lstatSync(localPath);
+      if (lstat.isFile()) {
+        const localHash = hashFile(localPath);
+        const journalEntry = journal.files[key];
+        if (journalEntry?.hash && journalEntry.hash !== localHash) {
+          // Local has unsynced edits — defer this tombstone.
+          continue;
+        }
+      } else if (lstat.isSymbolicLink()) {
+        // Codex P1 (PR #24 round 4): symlinks have target strings
+        // that can be locally edited too. Pre-fix, `isFile()` was
+        // false for symlinks so the divergence guard skipped them,
+        // and a locally-edited symlink (`ln -sfn new-target old-link`
+        // before the peer's remote-delete) was unlinked silently —
+        // the exact race the guard is meant to prevent. Compare the
+        // readlink hash against the journal baseline; defer on
+        // divergence. readlink errors (race / EACCES) also defer.
+        try {
+          const localHash = hashSymlinkTarget(fs.readlinkSync(localPath));
+          const journalEntry = journal.files[key];
+          if (journalEntry?.hash && journalEntry.hash !== localHash) {
+            continue;
+          }
+        } catch {
+          continue;
+        }
+      }
+      // Directories: no hash comparison. The tombstone executor's
+      // dir branch doesn't recursively rm-rf — it just drops the
+      // journal entry, which is the safe-by-default behavior.
+    } catch (err) {
+      const code =
+        err && typeof err === "object" && "code" in err
+          ? (err as { code?: string }).code
+          : undefined;
+      // ENOENT → local already gone; safe to drop journal entry via
+      // the executor's tombstone path.
+      // Other lstat errors (EACCES on parent dir, etc.) → defer:
+      // we can't read local state, so we can't safely decide.
+      if (code !== "ENOENT") continue;
+    }
+    tombstones.push(key);
+  }
+
   return {
     items,
     filesToDownload,
@@ -811,6 +1096,8 @@ function computePullPlan(
     filesToConflict,
     newFiles,
     newFilesCount: newFiles.length,
+    filesExcludedByPolicy,
+    tombstones,
   };
 }
 

package/src/ignore.test.ts

@@ -83,7 +83,7 @@ describe("createIgnoreFilter", () => {
     expect(shouldSync(path.join(hqRoot, ".claude/settings.json"))).toBe(true);
   });
 
-  it("permissive mode: .hq-* internal state is ignored, .hqignore family + .hq/ still sync", () => {
+  it("permissive mode: .hq-* internal state is ignored, .hqignore family still sync", () => {
     const shouldSync = createIgnoreFilter(hqRoot);
     // Internal state files that must never round-trip through the bucket.
     expect(shouldSync(path.join(hqRoot, ".hq-sync.pid"))).toBe(false);
@@ -92,11 +92,28 @@ describe("createIgnoreFilter", () => {
     expect(shouldSync(path.join(hqRoot, ".hq-embeddings-pending.json"))).toBe(false);
     expect(shouldSync(path.join(hqRoot, "companies/indigo/.hq-foo.json"))).toBe(false);
     expect(shouldSync(path.join(hqRoot, ".hq-cache/blob.bin"))).toBe(false);
-    // Sync-config files and the .hq/ directory still sync.
+    // Sync-config files still sync (no hyphen, doesn't match `.hq-*`).
     expect(shouldSync(path.join(hqRoot, ".hqignore"))).toBe(true);
     expect(shouldSync(path.join(hqRoot, ".hqsyncignore"))).toBe(true);
     expect(shouldSync(path.join(hqRoot, ".hqinclude"))).toBe(true);
-    expect(shouldSync(path.join(hqRoot, "companies/indigo/.hq/config.json"))).toBe(true);
+  });
+
+  it("permissive mode: .hq/ directory is per-host state, never synced (Bug #1/#6/#8)", () => {
+    // Bug catalog: `.hq/install-manifest.json`, `.hq/machine-id`, and
+    // `.hq/machine.json` are per-host source-of-truth files. The original
+    // `DEFAULT_IGNORES` only covered the `.hq-*` wildcard (with hyphen) and
+    // explicitly left the `.hq/` directory unaffected — so the install
+    // manifest and machine-id round-tripped through S3 between hosts,
+    // breaking the per-machine identity contract that the 5.33.0
+    // machine-id fix relies on.
+    const shouldSync = createIgnoreFilter(hqRoot);
+    expect(shouldSync(path.join(hqRoot, ".hq/install-manifest.json"))).toBe(false);
+    expect(shouldSync(path.join(hqRoot, ".hq/machine-id"))).toBe(false);
+    expect(shouldSync(path.join(hqRoot, ".hq/machine.json"))).toBe(false);
+    expect(shouldSync(path.join(hqRoot, ".hq/config.json"))).toBe(false);
+    expect(shouldSync(path.join(hqRoot, ".hq"), true)).toBe(false);
+    // Nested .hq/ inside a company also stays local (per-host scoping).
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/.hq/config.json"))).toBe(false);
   });
 
   it("allowlist mode: presence of .hqinclude switches to opt-in", () => {

package/src/ignore.ts

@@ -71,9 +71,15 @@ export const DEFAULT_IGNORES = [
   // covers `.hq-sync.pid`, `.hq-sync-journal.json`, `.hq-sync-state.json`,
   // `.hq-embeddings-pending.json`, and any future internal-state file. The
   // `.hqignore` / `.hqsyncignore` / `.hqinclude` config files don't match
-  // (no hyphen) and the `.hq/` directory is unaffected.
+  // (no hyphen). The `.hq/` directory holds per-host source-of-truth files
+  // (`install-manifest.json`, `machine-id`, `machine.json`, `config.json`)
+  // that MUST NEVER round-trip through the bucket — see Bug #1/#6/#8 in
+  // the 5.33.0 deep-test report. Leaking these between machines makes two
+  // hosts share an installer id / machine-id and breaks the contract the
+  // 5.33.0 machine-id fix relies on.
   "*.pid",
   ".hq-*",
+  ".hq/",
   "modules.lock",
   // hq-root identity marker — discovered locally per-machine, never synced.
   // Root-anchored: only the literal `core.yaml` at hq-root matches. Without

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* () {