@indigoai-us/hq-cli 5.19.0 → 5.21.0

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 ## [Unreleased]
 
+## [5.21.0] — 2026-05-24
+
+### Changed
+
+- Bumps `@indigoai-us/hq-cloud` to `~5.34.0` (was `~5.25.0`). 5.34.0
+  closes the 10-bug cross-machine sync cleanup from
+  [hq-cloud#24](https://github.com/indigoai-us/hq-cloud/pull/24) plus
+  the Codex P1/P2 follow-up safeties.
+
+  Highest-impact fixes that ride this bump:
+
+  - **Bug #9** (drifted files never converge): the pull walker on
+    `~5.25.0` had no tombstone-consumption mechanism, so cross-machine
+    deletes never propagated — every host kept the union of "every
+    file ever created anywhere." 5.34.0 lands journal-vs-LIST diff +
+    HEAD-verify STS-scope guard + local-edit divergence detector for
+    both files and symlinks. The Drift counter can finally reach zero.
+  - **Bug #7** (concurrent edit data loss): two open laptops editing
+    the same file before either had synced silently overwrote the
+    slower side on `~5.25.0` — no conflict event, no tray badge,
+    invisible data loss. 5.34.0 writes a mirror to
+    `<orig>.conflict-<ts>-<short>` instead.
+  - **Bug #10** (`ENOTDIR` wedges the whole company sync): one
+    dir-vs-file collision on a stale path on `~5.25.0` threw
+    `ENOTDIR` and aborted the whole company — `partial: true`,
+    `filesSkipped: 0`. 5.34.0 handles both `(local-file, cloud-dir)`
+    and `(local-dir, cloud-file)` topologies symmetrically.
+
+  Plus #1/#6/#8 (`.hq/` directory leak channel — including the
+  alternate `.hq/machine.json` and `.hq/install-manifest.json` paths
+  that were cross-polluting per-host identity), #2 (PULL walker now
+  applies `EPHEMERAL_PATH_PATTERN` — legacy `.conflict-*` litter no
+  longer ratchets), #3 (`conflictPaths` deduped within a company), #4
+  (dir-vs-file warning + structured event), and #5 (file mode
+  preserved across upload/download — was previously collapsing every
+  mode to receiver umask default).
+
+  New `SyncResult` fields surface via the runner's `complete` event:
+  `filesTombstoned`, `filesExcludedByPolicy`,
+  `filesRefusedStalePaths` (cap 50). hq-cli forwards them through
+  unchanged; the menubar can opt in via UI work in a follow-up.
+
+## [5.20.0] — 2026-05-21
+
+### Added
+
+- **`hq sync {push,pull,now} --all --no-personal`** — skip the
+  canonical-person leg of the `--all` fanout (companies-only sync).
+  Mirrors the upstream `hq-sync-runner --skip-personal` flag added in
+  `@indigoai-us/hq-cloud@5.25.0`. Wired so the AppBar HQ Sync menubar
+  can drop personal sync via a toggle, and so CLI users can opt out
+  one-off. Plumbed through `pullAll` / `pushAll` / `runNowAll` via a
+  new `skipPersonal` option; outside `--all` mode the flag is a no-op.
+- Bumps `@indigoai-us/hq-cloud` to `~5.25.0` (currency-gated personal-
+  vault default exclusions + skip-personal CLI/env surface).
+
 ## [5.18.3] — 2026-05-21
 
 ### Fixed

package/dist/commands/cloud.d.ts

@@ -77,6 +77,17 @@ export interface PullAllOptions {
      * legacy behavior for this run via `--mode-all`.
      */
     modeAllOverride?: boolean;
+    /**
+     * When `true`, skip the canonical-person-entity leg entirely — the
+     * fanout only visits the caller's company memberships. Mirrors the
+     * `--skip-personal` flag and `HQ_SYNC_SKIP_PERSONAL` env var that
+     * `@indigoai-us/hq-cloud`'s `sync-runner` exposes in `--companies`
+     * mode (see hq-cloud 5.25.0 `resolveSkipPersonal`). Surfaced on the
+     * CLI as `hq sync pull --all --no-personal` so the AppBar HQ Sync
+     * menubar toggle (and CLI users opting out one-off) can drop the
+     * personal vault from the run without touching the rest of the plan.
+     */
+    skipPersonal?: boolean;
 }
 export interface PullAllRow {
     slug: string;
@@ -110,6 +121,13 @@ export interface PushAllOptions {
     hqRoot: string;
     onConflict?: ConflictStrategy;
     message?: string;
+    /**
+     * When `true`, skip the canonical-person-entity leg entirely — the
+     * fanout only visits the caller's company memberships. Symmetric with
+     * `PullAllOptions.skipPersonal`; surfaced on the CLI as
+     * `hq sync push --all --no-personal`.
+     */
+    skipPersonal?: boolean;
 }
 export interface PushAllRow {
     slug: string;

package/dist/commands/cloud.js

@@ -13,7 +13,7 @@
  *   hq sync status            — show local journal summary
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f6dfc1de-3284-575a-b790-3dc10db2707c")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bdaf154f-b17d-5482-9e4d-feaebe606a1b")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
@@ -60,7 +60,7 @@ export async function pullAll(options, deps) {
             },
         });
     }
-    const personal = pickCanonicalPerson(persons);
+    const personal = options.skipPersonal ? null : pickCanonicalPerson(persons);
     if (personal) {
         plan.push({
             slug: "personal",
@@ -176,7 +176,7 @@ export async function pushAll(options, deps) {
             },
         });
     }
-    const personal = pickCanonicalPerson(persons);
+    const personal = options.skipPersonal ? null : pickCanonicalPerson(persons);
     if (personal) {
         plan.push({
             slug: "personal",
@@ -354,6 +354,12 @@ export function registerCloudCommands(program) {
         "every top-level entry under <hq-root> minus the excluded set " +
         "(.git, companies, repos, workspace) — same scope as `--all`'s " +
         "personal slot. Mutually exclusive with --company and --all.")
+        .option("--no-personal", "In `--all` mode, skip the canonical-person leg of the fanout — " +
+        "only push to the caller's company memberships. Mirrors the " +
+        "upstream `hq-sync-runner --skip-personal` flag (hq-cloud 5.25.0); " +
+        "wired so the AppBar HQ Sync menubar can drop personal sync via " +
+        "a toggle, and so CLI users can opt out one-off. Ignored outside " +
+        "`--all`.")
         .action(async (paths, options) => {
         try {
             assertSingleSelector(options, "push");
@@ -376,7 +382,13 @@ export function registerCloudCommands(program) {
                     "target instead.");
                 process.exit(1);
             }
-            await runPushAll(options.hqRoot, options.message, options.onConflict);
+            // `options.personal === false` happens when the user passed
+            // `--no-personal` (Commander's auto-negation of the `--personal`
+            // selector). In `--all` mode that means "skip the personal leg of
+            // the fanout" — wired through to `pushAll.skipPersonal`. Outside
+            // `--all` the flag has no effect (logged above as part of the
+            // option's help text).
+            await runPushAll(options.hqRoot, options.message, options.onConflict, options.personal === false);
             return;
         }
         const jsonMode = options.json === true;
@@ -531,6 +543,10 @@ export function registerCloudCommands(program) {
         "(no companies/<slug>/ prefix). Resolves the person UID automatically " +
         "from the cached Cognito session. Mutually exclusive with --company " +
         "and --all.")
+        .option("--no-personal", "In `--all` mode, skip the canonical-person leg of the fanout — " +
+        "only pull the caller's company memberships. Mirrors the upstream " +
+        "`hq-sync-runner --skip-personal` flag (hq-cloud 5.25.0). Ignored " +
+        "outside `--all`.")
         .option("--mode-all", "US-011: opt out of the strict narrow-hint refusal for this run. " +
         "Has no effect today (default narrow-hint level is 'hint'); " +
         "wired so future hq-core-staging releases can flip the default to " +
@@ -544,7 +560,10 @@ export function registerCloudCommands(program) {
             process.exit(1);
         }
         if (options.all) {
-            await runPullAll(options.hqRoot, options.onConflict, options.modeAll === true);
+            // `options.personal === false` is Commander's auto-negation of
+            // `--personal`; in `--all` mode that means "drop the personal
+            // leg from the fanout" (see `--no-personal` option above).
+            await runPullAll(options.hqRoot, options.onConflict, options.modeAll === true, options.personal === false);
             return;
         }
         if (options.personal) {
@@ -667,6 +686,10 @@ export function registerCloudCommands(program) {
         "--personal.")
         .option("--personal", "Sync the caller's canonical personal vault bidirectionally. " +
         "Mutually exclusive with --company and --all.")
+        .option("--no-personal", "In `--all` mode, skip the canonical-person leg of both the push " +
+        "and pull fanouts — only sync the caller's company memberships. " +
+        "Mirrors the upstream `hq-sync-runner --skip-personal` flag " +
+        "(hq-cloud 5.25.0). Ignored outside `--all`.")
         .option("--mode-all", "US-011: opt out of the strict narrow-hint refusal for this run. " +
         "No-op today; wired so future hq-core-staging releases can flip " +
         "the default narrow-hint level to 'strict'.")
@@ -674,7 +697,11 @@ export function registerCloudCommands(program) {
         try {
             assertSingleSelector(options, "now");
             if (options.all) {
-                await runNowAll(options.hqRoot, options.message, options.onConflict, options.modeAll === true);
+                // `options.personal === false` is Commander's auto-negation
+                // of `--personal`; in `--all` mode that means "drop the
+                // personal leg from both legs of the bidirectional fanout"
+                // (see `--no-personal` option above).
+                await runNowAll(options.hqRoot, options.message, options.onConflict, options.modeAll === true, options.personal === false);
                 return;
             }
             await runNowSingle(options.hqRoot, options.company, options.personal === true, options.message, options.onConflict, options.modeAll === true);
@@ -685,10 +712,14 @@ export function registerCloudCommands(program) {
         }
     });
 }
-async function runPullAll(hqRoot, onConflict, modeAllOverride) {
+async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal) {
     console.log(chalk.bold("\nHQ Sync — Pull (all)"));
     console.log(`  HQ root:  ${hqRoot}`);
-    console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+    console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
+    if (skipPersonal) {
+        console.log(`  Personal: skipped (--no-personal)`);
+    }
+    console.log("");
     let result;
     try {
         const accessToken = await ensureCognitoToken();
@@ -712,6 +743,7 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride) {
             ...(onConflict ? { onConflict } : {}),
             narrowHintLevel: resolveBannerLevel(),
             ...(modeAllOverride ? { modeAllOverride: true } : {}),
+            ...(skipPersonal ? { skipPersonal: true } : {}),
         }, {
             vaultClient: adapter,
             sync: (opts) => sync({
@@ -785,10 +817,14 @@ async function runPullPersonal(hqRoot, onConflict) {
         process.exit(1);
     }
 }
-async function runPushAll(hqRoot, message, onConflict) {
+async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
     console.log(chalk.bold("\nHQ Sync — Push (all)"));
     console.log(`  HQ root:  ${hqRoot}`);
-    console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+    console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
+    if (skipPersonal) {
+        console.log(`  Personal: skipped (--no-personal)`);
+    }
+    console.log("");
     let result;
     try {
         const accessToken = await ensureCognitoToken();
@@ -811,6 +847,7 @@ async function runPushAll(hqRoot, message, onConflict) {
             hqRoot,
             ...(onConflict ? { onConflict } : {}),
             ...(message ? { message } : {}),
+            ...(skipPersonal ? { skipPersonal: true } : {}),
         }, {
             vaultClient: adapter,
             share: (opts) => share({
@@ -1002,20 +1039,24 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         process.exit(1);
     }
 }
-async function runNowAll(hqRoot, message, onConflict, modeAllOverride) {
+async function runNowAll(hqRoot, message, onConflict, modeAllOverride, skipPersonal) {
     console.log(chalk.bold("\nHQ Sync — Now (all)"));
     console.log(`  HQ root:  ${hqRoot}`);
-    console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+    console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
+    if (skipPersonal) {
+        console.log(`  Personal: skipped (--no-personal)`);
+    }
+    console.log("");
     // Push first (matches runner), then pull. Re-uses the per-leg orchestrators
     // so the per-target rendering, error isolation, and exit codes are
     // identical to running `push --all` then `pull --all` back-to-back.
     console.log(chalk.dim("→ push --all"));
-    await runPushAll(hqRoot, message, onConflict);
+    await runPushAll(hqRoot, message, onConflict, skipPersonal);
     console.log(chalk.dim("\n→ pull --all"));
     // US-011: forward --mode-all so the strict refusal applies to the
     // pull leg (push doesn't need a narrow-hint — the narrow ritual is
     // pull-side).
-    await runPullAll(hqRoot, onConflict, modeAllOverride);
+    await runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal);
 }
 /**
  * Best-effort read of the active company slug from `<hqRoot>/.hq/config.json`.
@@ -1089,4 +1130,4 @@ function resolveUploadAuthorFromCache() {
     }
 }
 //# sourceMappingURL=cloud.js.map
-//# debugId=f6dfc1de-3284-575a-b790-3dc10db2707c
+//# debugId=bdaf154f-b17d-5482-9e4d-feaebe606a1b

package/dist/commands/pack-install.d.ts

@@ -54,6 +54,30 @@ export declare function sourceMatchesPackPattern(source: string): boolean;
  * contract this function pins.
  */
 export declare function installToPackages(payloadDir: string, pkg: PackManifest, hqRoot: string): string;
+/**
+ * Stamp the install-time `source:` into the destination package.yaml. This is
+ * the only on-disk record of which `recommended_packages[].source` produced
+ * each installed pack. `core/scripts/setup.sh` (hq-core >=14.2.x) reads
+ * `^source:` from every installed `core/packages/<name>/package.yaml` to dedup
+ * against `core/core.yaml:recommended_packages` — without this stamp, the
+ * dedup set is empty and every recommended pack is re-prompted on every
+ * setup.sh run.
+ *
+ * Idempotent: re-installs (and `hq update`) replace any pre-existing
+ * top-level `source:` line rather than duplicating it. Nested `source:`
+ * fields under `contributes:` (or any other block) are left untouched.
+ *
+ * The value is YAML double-quoted so `github:` sources containing `#`
+ * survive round-trip (an unquoted `#` would be parsed as a comment).
+ *
+ * If the manifest opens with a `---` YAML document marker, the source line is
+ * inserted *after* the marker — otherwise the prepend would create a
+ * two-document stream that single-doc `yaml.load` callers in this codebase
+ * cannot read.
+ *
+ * Exported for tests.
+ */
+export declare function stampInstallSource(destDir: string, source: string): void;
 /**
  * Run `<hqRoot>/core/scripts/scan-packages.sh` to wire the newly installed
  * pack's contributions into the host paths (skills, hooks, policies, etc.).

package/dist/commands/pack-install.js

@@ -34,7 +34,7 @@
  * from each pack's package.yaml; rationale lives in the layout-fix PR.)
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5dea7752-f10c-553c-a419-cf05441b3c13")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="845e5459-a7ba-53ca-a04c-dd055fabe52d")}catch(e){}}();
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -446,6 +446,61 @@ export function installToPackages(payloadDir, pkg, hqRoot) {
     execFileSync('rsync', ['-a', srcSlashed, destSlashed], { stdio: 'inherit' });
     return destDir;
 }
+/**
+ * Stamp the install-time `source:` into the destination package.yaml. This is
+ * the only on-disk record of which `recommended_packages[].source` produced
+ * each installed pack. `core/scripts/setup.sh` (hq-core >=14.2.x) reads
+ * `^source:` from every installed `core/packages/<name>/package.yaml` to dedup
+ * against `core/core.yaml:recommended_packages` — without this stamp, the
+ * dedup set is empty and every recommended pack is re-prompted on every
+ * setup.sh run.
+ *
+ * Idempotent: re-installs (and `hq update`) replace any pre-existing
+ * top-level `source:` line rather than duplicating it. Nested `source:`
+ * fields under `contributes:` (or any other block) are left untouched.
+ *
+ * The value is YAML double-quoted so `github:` sources containing `#`
+ * survive round-trip (an unquoted `#` would be parsed as a comment).
+ *
+ * If the manifest opens with a `---` YAML document marker, the source line is
+ * inserted *after* the marker — otherwise the prepend would create a
+ * two-document stream that single-doc `yaml.load` callers in this codebase
+ * cannot read.
+ *
+ * Exported for tests.
+ */
+export function stampInstallSource(destDir, source) {
+    const manifestPath = path.join(destDir, 'package.yaml');
+    if (!fs.existsSync(manifestPath)) {
+        // installToPackages already validated the payload contained package.yaml.
+        // If it's gone by the time we stamp, something deleted it between calls —
+        // fail loud so the regression surfaces in tests.
+        throw new Error(`stampInstallSource: ${manifestPath} not found`);
+    }
+    const original = fs.readFileSync(manifestPath, 'utf-8');
+    // Strip any existing top-level `source:` line. Match only lines starting at
+    // column 0 so nested `source:` fields (none in spec today, but defensive)
+    // are not touched.
+    const lines = original.split('\n').filter((line) => !/^source\s*:/.test(line));
+    const quoted = `"${source.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+    const sourceLine = `source: ${quoted}`;
+    // Detect a leading YAML document marker (`---`, optionally followed by
+    // trailing whitespace or a comment). If present, the source line goes
+    // *after* it so the manifest stays a single document.
+    let insertAt = 0;
+    while (insertAt < lines.length && lines[insertAt].trim() === '')
+        insertAt++;
+    const opensWithDocMarker = insertAt < lines.length && /^---(\s|#|$)/.test(lines[insertAt]);
+    if (opensWithDocMarker) {
+        lines.splice(insertAt + 1, 0, sourceLine);
+    }
+    else {
+        // Drop any leading blank lines we walked past so the file doesn't grow a
+        // blank-line gutter on every re-stamp.
+        lines.splice(0, insertAt, sourceLine);
+    }
+    fs.writeFileSync(manifestPath, lines.join('\n'));
+}
 /**
  * Run `<hqRoot>/core/scripts/scan-packages.sh` to wire the newly installed
  * pack's contributions into the host paths (skills, hooks, policies, etc.).
@@ -509,12 +564,15 @@ export async function installPack(source, opts = {}) {
             return;
         }
         const destDir = installToPackages(fetched.payloadDir, pkg, hqRoot);
-        // Under the v12 HQ layout, packs live at `core/packages/<name>/` and are
-        // tracked by filesystem presence alone — no `modules.yaml` write. That
-        // removes the side effect that created a top-level `modules/` directory
-        // alongside the canonical `core/`. `hq update <pack>` will re-resolve a
-        // pack's source from its on-disk package.yaml or prompt for it, but that
-        // tradeoff is intentional — see the layout-fix PR for rationale.
+        // Under the v12+ HQ layout, packs live at `core/packages/<name>/` and
+        // are tracked by filesystem presence — no `modules.yaml` write (that
+        // removed the orphan top-level `modules/` tree alongside the canonical
+        // `core/`). The one piece of install-time provenance we DO record is the
+        // input `source` string, stamped into the destination `package.yaml` so
+        // setup.sh can dedup against `core/core.yaml:recommended_packages` on
+        // re-runs. Stamping the literal input (not the resolved SHA/version)
+        // matches the verbatim equality check in setup.sh.
+        stampInstallSource(destDir, source);
         runScanPackages(hqRoot);
         console.log(chalk.green(`\n✓ Installed ${pkg.name}@${pkg.version} → ${path.relative(hqRoot, destDir)}/`));
         console.log(chalk.dim(`  Wired ${Object.values(pkg.contributes).flat().filter(Boolean).length} ` +
@@ -525,4 +583,4 @@ export async function installPack(source, opts = {}) {
     }
 }
 //# sourceMappingURL=pack-install.js.map
-//# debugId=5dea7752-f10c-553c-a419-cf05441b3c13
+//# debugId=845e5459-a7ba-53ca-a04c-dd055fabe52d

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.19.0",
+  "version": "5.21.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -15,7 +15,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@indigoai-us/hq-cloud": "^5.23.0",
+    "@indigoai-us/hq-cloud": "~5.34.0",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "chalk": "^5.3.0",

package/src/commands/cloud.pull-all.test.ts

@@ -493,4 +493,102 @@ describe("pullAll", () => {
       expect(call.hqRoot).toBe("/Users/me/scratch/hq");
     }
   });
+
+  // ── 11. skipPersonal — fanout omits the canonical-person leg ──────────────
+  //
+  // Mirrors the upstream `hq-sync-runner --skip-personal` flag (hq-cloud
+  // 5.25.0) plumbed through to the CLI as `hq sync pull --all --no-personal`.
+  // When the option is true, `pullAll` must (a) skip the canonical-person
+  // bucket even when one exists, and (b) leave companies untouched.
+
+  it("skipPersonal=true omits the personal leg even when a person entity exists", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [
+        { companyUid: "cmp_acme" },
+        { companyUid: "cmp_globex" },
+      ],
+      persons: [
+        {
+          uid: "psn_alice",
+          type: "person",
+          slug: "alice",
+          bucketName: "hq-vault-psn-alice",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+      ],
+      entitiesBySlug: {
+        cmp_acme: { slug: "acme" },
+        cmp_globex: { slug: "globex" },
+      },
+    });
+    const sync = makeSyncSpy();
+
+    const result = await pullAll(
+      { hqRoot: "/tmp/hq", skipPersonal: true },
+      { vaultClient, sync: sync.fn },
+    );
+
+    expect(sync.calls.map((c) => c.company)).toEqual([
+      "cmp_acme",
+      "cmp_globex",
+    ]);
+    for (const call of sync.calls) {
+      expect(call.personalMode).toBeUndefined();
+      expect(call.journalSlug).toBeUndefined();
+    }
+    expect(result.attempted).toBe(2);
+    expect(result.perCompany.map((r) => r.slug)).toEqual(["acme", "globex"]);
+  });
+
+  it("skipPersonal omitted/false keeps the personal leg in the fanout (baseline)", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [{ companyUid: "cmp_acme" }],
+      persons: [
+        {
+          uid: "psn_alice",
+          type: "person",
+          slug: "alice",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+      ],
+      entitiesBySlug: { cmp_acme: { slug: "acme" } },
+    });
+    const sync = makeSyncSpy();
+
+    await pullAll(
+      { hqRoot: "/tmp/hq" },
+      { vaultClient, sync: sync.fn },
+    );
+
+    expect(sync.calls.map((c) => c.company)).toEqual([
+      "cmp_acme",
+      "psn_alice",
+    ]);
+    expect(sync.calls[1].personalMode).toBe(true);
+    expect(sync.calls[1].journalSlug).toBe("personal");
+  });
+
+  it("skipPersonal=true with empty memberships produces zero sync calls", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [],
+      persons: [
+        {
+          uid: "psn_alice",
+          type: "person",
+          slug: "alice",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+      ],
+    });
+    const sync = makeSyncSpy();
+
+    const result = await pullAll(
+      { hqRoot: "/tmp/hq", skipPersonal: true },
+      { vaultClient, sync: sync.fn },
+    );
+
+    expect(sync.calls).toEqual([]);
+    expect(result.attempted).toBe(0);
+    expect(result.perCompany).toEqual([]);
+  });
 });

package/src/commands/cloud.push-all.test.ts

@@ -378,4 +378,79 @@ describe("pushAll", () => {
     expect(result.filesUploaded).toBe(3);
     expect(result.filesDeleted).toBe(4);
   });
+
+  // ── skipPersonal — fanout omits the canonical-person leg ──────────────────
+  //
+  // Symmetric with the `pullAll` skipPersonal coverage in
+  // `cloud.pull-all.test.ts`. Wired through from `hq sync push --all
+  // --no-personal` (Commander's `--no-personal` is the auto-negation of the
+  // `--personal` single-target selector). Verifies (a) the personal leg is
+  // dropped even when a canonical person exists, and (b) the baseline
+  // behavior — no flag → personal stays in the plan.
+
+  it("skipPersonal=true omits the personal leg even when a person entity exists", async () => {
+    const hqRoot = makeHqRoot([".git", "companies", "repos", "workspace"]);
+    const vaultClient = makeVaultClient({
+      memberships: [
+        { companyUid: "cmp_acme" },
+        { companyUid: "cmp_globex" },
+      ],
+      persons: [
+        {
+          uid: "psn_alice",
+          type: "person",
+          slug: "alice",
+          bucketName: "hq-vault-psn-alice",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+      ],
+      entitiesBySlug: {
+        cmp_acme: { slug: "acme" },
+        cmp_globex: { slug: "globex" },
+      },
+    });
+    const share = makeShareSpy();
+
+    const result = await pushAll(
+      { hqRoot, skipPersonal: true },
+      { vaultClient, share: share.fn },
+    );
+
+    expect(share.calls.map((c) => c.company)).toEqual([
+      "cmp_acme",
+      "cmp_globex",
+    ]);
+    for (const call of share.calls) {
+      expect(call.personalMode).toBeUndefined();
+      expect(call.journalSlug).toBeUndefined();
+    }
+    expect(result.attempted).toBe(2);
+    expect(result.perCompany.map((r) => r.slug)).toEqual(["acme", "globex"]);
+  });
+
+  it("skipPersonal omitted keeps the personal leg in the plan (baseline)", async () => {
+    const hqRoot = makeHqRoot([".git", "companies", "repos", "workspace"]);
+    const vaultClient = makeVaultClient({
+      memberships: [{ companyUid: "cmp_acme" }],
+      persons: [
+        {
+          uid: "psn_alice",
+          type: "person",
+          slug: "alice",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+      ],
+      entitiesBySlug: { cmp_acme: { slug: "acme" } },
+    });
+    const share = makeShareSpy();
+
+    await pushAll({ hqRoot }, { vaultClient, share: share.fn });
+
+    expect(share.calls.map((c) => c.company)).toEqual([
+      "cmp_acme",
+      "psn_alice",
+    ]);
+    expect(share.calls[1].personalMode).toBe(true);
+    expect(share.calls[1].journalSlug).toBe("personal");
+  });
 });

package/src/commands/cloud.ts

@@ -125,6 +125,17 @@ export interface PullAllOptions {
    * legacy behavior for this run via `--mode-all`.
    */
   modeAllOverride?: boolean;
+  /**
+   * When `true`, skip the canonical-person-entity leg entirely — the
+   * fanout only visits the caller's company memberships. Mirrors the
+   * `--skip-personal` flag and `HQ_SYNC_SKIP_PERSONAL` env var that
+   * `@indigoai-us/hq-cloud`'s `sync-runner` exposes in `--companies`
+   * mode (see hq-cloud 5.25.0 `resolveSkipPersonal`). Surfaced on the
+   * CLI as `hq sync pull --all --no-personal` so the AppBar HQ Sync
+   * menubar toggle (and CLI users opting out one-off) can drop the
+   * personal vault from the run without touching the rest of the plan.
+   */
+  skipPersonal?: boolean;
 }
 
 export interface PullAllRow {
@@ -173,6 +184,13 @@ export interface PushAllOptions {
   hqRoot: string;
   onConflict?: ConflictStrategy;
   message?: string;
+  /**
+   * When `true`, skip the canonical-person-entity leg entirely — the
+   * fanout only visits the caller's company memberships. Symmetric with
+   * `PullAllOptions.skipPersonal`; surfaced on the CLI as
+   * `hq sync push --all --no-personal`.
+   */
+  skipPersonal?: boolean;
 }
 
 export interface PushAllRow {
@@ -252,7 +270,7 @@ export async function pullAll(
     });
   }
 
-  const personal = pickCanonicalPerson(persons);
+  const personal = options.skipPersonal ? null : pickCanonicalPerson(persons);
   if (personal) {
     plan.push({
       slug: "personal",
@@ -385,7 +403,7 @@ export async function pushAll(
     });
   }
 
-  const personal = pickCanonicalPerson(persons);
+  const personal = options.skipPersonal ? null : pickCanonicalPerson(persons);
   if (personal) {
     plan.push({
       slug: "personal",
@@ -637,6 +655,15 @@ export function registerCloudCommands(program: Command): void {
         "(.git, companies, repos, workspace) — same scope as `--all`'s " +
         "personal slot. Mutually exclusive with --company and --all.",
     )
+    .option(
+      "--no-personal",
+      "In `--all` mode, skip the canonical-person leg of the fanout — " +
+        "only push to the caller's company memberships. Mirrors the " +
+        "upstream `hq-sync-runner --skip-personal` flag (hq-cloud 5.25.0); " +
+        "wired so the AppBar HQ Sync menubar can drop personal sync via " +
+        "a toggle, and so CLI users can opt out one-off. Ignored outside " +
+        "`--all`.",
+    )
     .action(
       async (
         paths: string[],
@@ -678,10 +705,17 @@ export function registerCloudCommands(program: Command): void {
             );
             process.exit(1);
           }
+          // `options.personal === false` happens when the user passed
+          // `--no-personal` (Commander's auto-negation of the `--personal`
+          // selector). In `--all` mode that means "skip the personal leg of
+          // the fanout" — wired through to `pushAll.skipPersonal`. Outside
+          // `--all` the flag has no effect (logged above as part of the
+          // option's help text).
           await runPushAll(
             options.hqRoot,
             options.message,
             options.onConflict,
+            options.personal === false,
           );
           return;
         }
@@ -885,6 +919,13 @@ export function registerCloudCommands(program: Command): void {
         "from the cached Cognito session. Mutually exclusive with --company " +
         "and --all.",
     )
+    .option(
+      "--no-personal",
+      "In `--all` mode, skip the canonical-person leg of the fanout — " +
+        "only pull the caller's company memberships. Mirrors the upstream " +
+        "`hq-sync-runner --skip-personal` flag (hq-cloud 5.25.0). Ignored " +
+        "outside `--all`.",
+    )
     .option(
       "--mode-all",
       "US-011: opt out of the strict narrow-hint refusal for this run. " +
@@ -911,10 +952,14 @@ export function registerCloudCommands(program: Command): void {
           process.exit(1);
         }
         if (options.all) {
+          // `options.personal === false` is Commander's auto-negation of
+          // `--personal`; in `--all` mode that means "drop the personal
+          // leg from the fanout" (see `--no-personal` option above).
           await runPullAll(
             options.hqRoot,
             options.onConflict,
             options.modeAll === true,
+            options.personal === false,
           );
           return;
         }
@@ -1100,6 +1145,13 @@ export function registerCloudCommands(program: Command): void {
       "Sync the caller's canonical personal vault bidirectionally. " +
         "Mutually exclusive with --company and --all.",
     )
+    .option(
+      "--no-personal",
+      "In `--all` mode, skip the canonical-person leg of both the push " +
+        "and pull fanouts — only sync the caller's company memberships. " +
+        "Mirrors the upstream `hq-sync-runner --skip-personal` flag " +
+        "(hq-cloud 5.25.0). Ignored outside `--all`.",
+    )
     .option(
       "--mode-all",
       "US-011: opt out of the strict narrow-hint refusal for this run. " +
@@ -1119,11 +1171,16 @@ export function registerCloudCommands(program: Command): void {
         try {
           assertSingleSelector(options, "now");
           if (options.all) {
+            // `options.personal === false` is Commander's auto-negation
+            // of `--personal`; in `--all` mode that means "drop the
+            // personal leg from both legs of the bidirectional fanout"
+            // (see `--no-personal` option above).
             await runNowAll(
               options.hqRoot,
               options.message,
               options.onConflict,
               options.modeAll === true,
+              options.personal === false,
             );
             return;
           }
@@ -1150,10 +1207,15 @@ async function runPullAll(
   hqRoot: string,
   onConflict?: ConflictStrategy,
   modeAllOverride?: boolean,
+  skipPersonal?: boolean,
 ): Promise<void> {
   console.log(chalk.bold("\nHQ Sync — Pull (all)"));
   console.log(`  HQ root:  ${hqRoot}`);
-  console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+  console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
+  if (skipPersonal) {
+    console.log(`  Personal: skipped (--no-personal)`);
+  }
+  console.log("");
 
   let result: PullAllResult;
   try {
@@ -1181,6 +1243,7 @@ async function runPullAll(
         ...(onConflict ? { onConflict } : {}),
         narrowHintLevel: resolveBannerLevel(),
         ...(modeAllOverride ? { modeAllOverride: true } : {}),
+        ...(skipPersonal ? { skipPersonal: true } : {}),
       },
       {
         vaultClient: adapter,
@@ -1285,10 +1348,15 @@ async function runPushAll(
   hqRoot: string,
   message?: string,
   onConflict?: ConflictStrategy,
+  skipPersonal?: boolean,
 ): Promise<void> {
   console.log(chalk.bold("\nHQ Sync — Push (all)"));
   console.log(`  HQ root:  ${hqRoot}`);
-  console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+  console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
+  if (skipPersonal) {
+    console.log(`  Personal: skipped (--no-personal)`);
+  }
+  console.log("");
 
   let result: PushAllResult;
   try {
@@ -1314,6 +1382,7 @@ async function runPushAll(
         hqRoot,
         ...(onConflict ? { onConflict } : {}),
         ...(message ? { message } : {}),
+        ...(skipPersonal ? { skipPersonal: true } : {}),
       },
       {
         vaultClient: adapter,
@@ -1552,21 +1621,26 @@ async function runNowAll(
   message?: string,
   onConflict?: ConflictStrategy,
   modeAllOverride?: boolean,
+  skipPersonal?: boolean,
 ): Promise<void> {
   console.log(chalk.bold("\nHQ Sync — Now (all)"));
   console.log(`  HQ root:  ${hqRoot}`);
-  console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+  console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
+  if (skipPersonal) {
+    console.log(`  Personal: skipped (--no-personal)`);
+  }
+  console.log("");
 
   // Push first (matches runner), then pull. Re-uses the per-leg orchestrators
   // so the per-target rendering, error isolation, and exit codes are
   // identical to running `push --all` then `pull --all` back-to-back.
   console.log(chalk.dim("→ push --all"));
-  await runPushAll(hqRoot, message, onConflict);
+  await runPushAll(hqRoot, message, onConflict, skipPersonal);
   console.log(chalk.dim("\n→ pull --all"));
   // US-011: forward --mode-all so the strict refusal applies to the
   // pull leg (push doesn't need a narrow-hint — the narrow ritual is
   // pull-side).
-  await runPullAll(hqRoot, onConflict, modeAllOverride);
+  await runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal);
 }
 
 /**

package/src/commands/pack-install.test.ts

@@ -21,7 +21,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { installToPackages, runScanPackages } from './pack-install.js';
+import { installToPackages, runScanPackages, stampInstallSource } from './pack-install.js';
 import type { PackManifest } from '../types.js';
 
 // ---------------------------------------------------------------------------
@@ -145,4 +145,118 @@ describe('pack-install: install path layout', () => {
     expect(fs.existsSync(path.join(hqRoot, 'modules'))).toBe(false);
     expect(fs.existsSync(path.join(hqRoot, 'modules.yaml'))).toBe(false);
   });
+
+  // ---- 5. stampInstallSource — setup.sh dedup contract --------------------
+  // setup.sh in hq-core ≥14.2.x reads `^source:` from every installed
+  // core/packages/*/package.yaml and uses verbatim equality against
+  // core.yaml:recommended_packages[].source to skip "already installed" packs.
+  // Without the stamp the dedup set is empty and every recommended pack gets
+  // re-prompted on every setup.sh run — the bug this stamp closes.
+  it('stampInstallSource writes a top-level source: line into package.yaml', () => {
+    const dest = installToPackages(payload, fakeManifest({ name: 'hq-pack-test' }), hqRoot);
+    const src = '@indigoai-us/hq-pack-test@1.2.3';
+    stampInstallSource(dest, src);
+
+    const written = fs.readFileSync(path.join(dest, 'package.yaml'), 'utf-8');
+    // First line so a `grep ^source:` style scan never misses it.
+    expect(written.split('\n')[0]).toBe(`source: "${src}"`);
+    // Original fields preserved verbatim — the stamp must not clobber name/version.
+    expect(written).toContain('name: hq-pack-test');
+    expect(written).toContain('version: 1.0.0');
+  });
+
+  it('stampInstallSource is idempotent — re-install replaces (not duplicates) the source line', () => {
+    const dest = installToPackages(payload, fakeManifest({ name: 'hq-pack-test' }), hqRoot);
+    stampInstallSource(dest, '@indigoai-us/hq-pack-test@1.0.0');
+    stampInstallSource(dest, '@indigoai-us/hq-pack-test@1.2.3');
+
+    const written = fs.readFileSync(path.join(dest, 'package.yaml'), 'utf-8');
+    // Exactly one top-level source: line, and it carries the latest value.
+    const sourceLines = written.split('\n').filter((l) => /^source\s*:/.test(l));
+    expect(sourceLines).toHaveLength(1);
+    expect(sourceLines[0]).toBe('source: "@indigoai-us/hq-pack-test@1.2.3"');
+  });
+
+  it('stampInstallSource quotes github: sources so the # is not parsed as a YAML comment', () => {
+    const dest = installToPackages(payload, fakeManifest({ name: 'hq-pack-test' }), hqRoot);
+    const src = 'github:indigoai-us/hq-packages#packages/hq-pack-test';
+    stampInstallSource(dest, src);
+
+    const written = fs.readFileSync(path.join(dest, 'package.yaml'), 'utf-8');
+    // Double-quoted form survives the '#' that would otherwise truncate the
+    // value at the first YAML comment marker.
+    expect(written.split('\n')[0]).toBe(`source: "${src}"`);
+    // Round-trip through js-yaml to confirm a real parser reads the full value.
+    const yamlLib = require('js-yaml');
+    const parsed = yamlLib.load(written) as { source: string };
+    expect(parsed.source).toBe(src);
+  });
+
+  it('stampInstallSource only strips top-level source: lines, not nested ones', () => {
+    // Defensive: today's spec has no nested `source:` keys, but if a pack
+    // author adds e.g. `metadata: { source: ... }` we should leave it alone.
+    const dest = installToPackages(payload, fakeManifest({ name: 'hq-pack-test' }), hqRoot);
+    fs.writeFileSync(
+      path.join(dest, 'package.yaml'),
+      [
+        'name: hq-pack-test',
+        'version: 1.0.0',
+        'metadata:',
+        '  source: nested-value-keep-me',
+        '',
+      ].join('\n'),
+    );
+
+    stampInstallSource(dest, '@indigoai-us/hq-pack-test@1.0.0');
+
+    const written = fs.readFileSync(path.join(dest, 'package.yaml'), 'utf-8');
+    expect(written.split('\n')[0]).toBe('source: "@indigoai-us/hq-pack-test@1.0.0"');
+    // Nested source line survives.
+    expect(written).toContain('  source: nested-value-keep-me');
+  });
+
+  it('stampInstallSource throws when package.yaml is missing — surfaces upstream regressions loudly', () => {
+    const dest = installToPackages(payload, fakeManifest({ name: 'hq-pack-test' }), hqRoot);
+    fs.unlinkSync(path.join(dest, 'package.yaml'));
+
+    expect(() => stampInstallSource(dest, '@scope/x@1.0.0')).toThrow(/package\.yaml.*not found/);
+  });
+
+  it('stampInstallSource preserves a leading `---` document marker — no multi-doc YAML stream', () => {
+    // Regression: prepending `source:` before a `---` would split the file
+    // into two YAML documents, and single-doc `yaml.load` callers downstream
+    // (in this codebase + hq-core) silently misread or fail. Insert AFTER
+    // the marker so the manifest stays a single document.
+    const dest = installToPackages(payload, fakeManifest({ name: 'hq-pack-test' }), hqRoot);
+    fs.writeFileSync(
+      path.join(dest, 'package.yaml'),
+      ['---', 'name: hq-pack-test', 'version: 1.0.0', ''].join('\n'),
+    );
+    const src = 'github:indigoai-us/hq-packages#packages/hq-pack-test';
+
+    stampInstallSource(dest, src);
+
+    const written = fs.readFileSync(path.join(dest, 'package.yaml'), 'utf-8');
+    // `---` stays on line 0, `source:` follows immediately so `grep ^source:`
+    // dedup scans still match.
+    const lines = written.split('\n');
+    expect(lines[0]).toBe('---');
+    expect(lines[1]).toBe(`source: "${src}"`);
+
+    // Critical assertion: js-yaml's single-doc loader returns the merged
+    // manifest, not just the first of two documents.
+    const yamlLib = require('js-yaml');
+    const parsed = yamlLib.load(written) as { source: string; name: string; version: string };
+    expect(parsed.source).toBe(src);
+    expect(parsed.name).toBe('hq-pack-test');
+    expect(parsed.version).toBe('1.0.0');
+
+    // Re-stamp is still idempotent in the doc-marker case.
+    stampInstallSource(dest, '@scope/x@2.0.0');
+    const rewritten = fs.readFileSync(path.join(dest, 'package.yaml'), 'utf-8');
+    const sourceLines = rewritten.split('\n').filter((l) => /^source\s*:/.test(l));
+    expect(sourceLines).toHaveLength(1);
+    expect(sourceLines[0]).toBe('source: "@scope/x@2.0.0"');
+    expect(rewritten.split('\n')[0]).toBe('---');
+  });
 });

package/src/commands/pack-install.ts

@@ -547,6 +547,62 @@ export function installToPackages(
   return destDir;
 }
 
+/**
+ * Stamp the install-time `source:` into the destination package.yaml. This is
+ * the only on-disk record of which `recommended_packages[].source` produced
+ * each installed pack. `core/scripts/setup.sh` (hq-core >=14.2.x) reads
+ * `^source:` from every installed `core/packages/<name>/package.yaml` to dedup
+ * against `core/core.yaml:recommended_packages` — without this stamp, the
+ * dedup set is empty and every recommended pack is re-prompted on every
+ * setup.sh run.
+ *
+ * Idempotent: re-installs (and `hq update`) replace any pre-existing
+ * top-level `source:` line rather than duplicating it. Nested `source:`
+ * fields under `contributes:` (or any other block) are left untouched.
+ *
+ * The value is YAML double-quoted so `github:` sources containing `#`
+ * survive round-trip (an unquoted `#` would be parsed as a comment).
+ *
+ * If the manifest opens with a `---` YAML document marker, the source line is
+ * inserted *after* the marker — otherwise the prepend would create a
+ * two-document stream that single-doc `yaml.load` callers in this codebase
+ * cannot read.
+ *
+ * Exported for tests.
+ */
+export function stampInstallSource(destDir: string, source: string): void {
+  const manifestPath = path.join(destDir, 'package.yaml');
+  if (!fs.existsSync(manifestPath)) {
+    // installToPackages already validated the payload contained package.yaml.
+    // If it's gone by the time we stamp, something deleted it between calls —
+    // fail loud so the regression surfaces in tests.
+    throw new Error(`stampInstallSource: ${manifestPath} not found`);
+  }
+  const original = fs.readFileSync(manifestPath, 'utf-8');
+  // Strip any existing top-level `source:` line. Match only lines starting at
+  // column 0 so nested `source:` fields (none in spec today, but defensive)
+  // are not touched.
+  const lines = original.split('\n').filter((line) => !/^source\s*:/.test(line));
+  const quoted = `"${source.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  const sourceLine = `source: ${quoted}`;
+
+  // Detect a leading YAML document marker (`---`, optionally followed by
+  // trailing whitespace or a comment). If present, the source line goes
+  // *after* it so the manifest stays a single document.
+  let insertAt = 0;
+  while (insertAt < lines.length && lines[insertAt].trim() === '') insertAt++;
+  const opensWithDocMarker =
+    insertAt < lines.length && /^---(\s|#|$)/.test(lines[insertAt]);
+  if (opensWithDocMarker) {
+    lines.splice(insertAt + 1, 0, sourceLine);
+  } else {
+    // Drop any leading blank lines we walked past so the file doesn't grow a
+    // blank-line gutter on every re-stamp.
+    lines.splice(0, insertAt, sourceLine);
+  }
+  fs.writeFileSync(manifestPath, lines.join('\n'));
+}
+
 /**
  * Run `<hqRoot>/core/scripts/scan-packages.sh` to wire the newly installed
  * pack's contributions into the host paths (skills, hooks, policies, etc.).
@@ -640,12 +696,15 @@ export async function installPack(
     }
 
     const destDir = installToPackages(fetched.payloadDir, pkg, hqRoot);
-    // Under the v12 HQ layout, packs live at `core/packages/<name>/` and are
-    // tracked by filesystem presence alone — no `modules.yaml` write. That
-    // removes the side effect that created a top-level `modules/` directory
-    // alongside the canonical `core/`. `hq update <pack>` will re-resolve a
-    // pack's source from its on-disk package.yaml or prompt for it, but that
-    // tradeoff is intentional — see the layout-fix PR for rationale.
+    // Under the v12+ HQ layout, packs live at `core/packages/<name>/` and
+    // are tracked by filesystem presence — no `modules.yaml` write (that
+    // removed the orphan top-level `modules/` tree alongside the canonical
+    // `core/`). The one piece of install-time provenance we DO record is the
+    // input `source` string, stamped into the destination `package.yaml` so
+    // setup.sh can dedup against `core/core.yaml:recommended_packages` on
+    // re-runs. Stamping the literal input (not the resolved SHA/version)
+    // matches the verbatim equality check in setup.sh.
+    stampInstallSource(destDir, source);
     runScanPackages(hqRoot);
 
     console.log(