@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/commands/cloud.js

@@ -16,10 +16,16 @@ import { isAccessDeniedError, accessDeniedKeyOf, formatAccessDenied, } from "../
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
-import { share, sync, getStateDir, listJournals, loadCachedTokens, VaultClient, computePersonalVaultPaths, PERSONAL_VAULT_JOURNAL_SLUG, resolvePullScope, syncDoctor, } from "@indigoai-us/hq-cloud";
+import { share, sync, getStateDir, listJournals, VaultClient, computePersonalVaultPaths, PERSONAL_VAULT_JOURNAL_SLUG, resolvePullScope, syncDoctor, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
+import { resolveUploadAuthor } from "../utils/upload-author.js";
 import { companyFolderExceedsThreshold, emitNarrowHint, isStrictRefusal, resolveBannerLevel, resolveNarrowHintPresentationLevel, resolveNarrowHintMinBytes, } from "../lib/narrow-hint-banner.js";
 import { beginSyncHealthReport, } from "../utils/client-health.js";
+import { recordFirstWorkBearingSync } from "../lib/first-sync-next-step.js";
+import { createPlanLimitRefusalTracker, describeRefusedCount, describeRefusedFiles, mergePlanLimitRefusals, renderPlanLimitRefusalLines, trackingProgressRecorder, } from "../lib/billing/plan-limit-refusals.js";
+import { formatPlanGateError, planGateErrorFromVaultError, } from "../utils/plan-gate-error.js";
+import { personalTargetedPushPathsEnabled } from "./personal-targeted-push-flag.js";
+import { resolveExplicitPersonalPushPaths } from "./personal-targeted-push-paths.js";
 /**
  * Terminal-failure signal for the sync fanout runners. The runners
  * (`runPushAll` / `runPullAll` / `runPullPersonal` / `runNowSingle` /
@@ -33,18 +39,41 @@ import { beginSyncHealthReport, } from "../utils/client-health.js";
  */
 export class SyncExitError extends Error {
     code;
-    constructor(code) {
+    /**
+     * The client-health outcome to record for this exit. A run whose only
+     * problem was a plan-limit refusal exits non-zero (it did not upload what
+     * was asked) but is not a sync failure: the engine worked and the refusal
+     * is plan state, so it must not count toward `consecutiveFailures`.
+     */
+    health;
+    constructor(code, opts = {}) {
         super(`sync command exit ${code}`);
         this.code = code;
         this.name = "SyncExitError";
+        this.health = opts.health ?? "failed";
     }
 }
+async function ensureSyncCognitoToken() {
+    return ensureCognitoToken({
+        interactive: process.stdin.isTTY === true && process.stdout.isTTY === true,
+    });
+}
 /**
  * Preserve the vault's typed write-scope refusal at the CLI boundary. This is
  * deliberately duck-typed so hq-cli remains compatible while hq-cloud and the
  * CLI are released independently.
  */
 export function formatSyncFailure(err) {
+    // A plan-limit refusal the runner threw (a 402 on the whole request) renders
+    // with the same reason, fix options and upgrade link as every other refusal.
+    const planGate = planGateErrorFromVaultError(err);
+    if (planGate) {
+        const refusedPath = typeof err.path === "string"
+            ? err.path
+            : undefined;
+        return (formatPlanGateError(planGate) +
+            (refusedPath ? `\nNot uploaded: ${refusedPath}` : ""));
+    }
     if (isAccessDeniedError(err)) {
         const key = accessDeniedKeyOf(err);
         const base = err instanceof Error ? err.message : String(err);
@@ -90,7 +119,12 @@ export async function withSyncHealthReport(run) {
         return result;
     }
     catch (err) {
-        await health.failed();
+        if (err instanceof SyncExitError && err.health === "succeeded") {
+            await health.succeeded();
+        }
+        else {
+            await health.failed();
+        }
         if (err instanceof SyncExitError)
             process.exit(err.code);
         throw err;
@@ -115,11 +149,39 @@ export function scopeExcludedWarning(count) {
  * dropped files — helps debug ACL vs scope-excluded mismatches (feedback_7e9c535e).
  */
 export function scopeExcludedPrefixDetail(prefixSet) {
-    if (!prefixSet || prefixSet.length === 0) {
+    // No client-side prefix scope applied: the server refused the paths one by
+    // one, and scopeExcludedLines' primary line already says so.
+    if (prefixSet === undefined)
+        return null;
+    if (prefixSet.length === 0) {
         return "  Granted write prefixes: (none — shared-mode membership with no explicit grants)";
     }
     return `  Granted write prefixes: ${prefixSet.join(", ")}`;
 }
+/**
+ * Every warning line for a push that dropped files, shared by `push`, `now`
+ * and `push --all`. With a client prefix scope the files fell outside the
+ * caller's write prefixes; without one (prefixSet undefined) the server
+ * refused them path by path — typically another member's child in a private
+ * folder foo/ — and grant advice would point the reader the wrong way.
+ */
+export function scopeExcludedLines(count, prefixSet) {
+    if (count <= 0)
+        return [];
+    if (prefixSet === undefined) {
+        return [
+            `⚠ ${count} file(s) were NOT uploaded — the server refused them. ` +
+                `A common cause is a file someone else created in a private folder ` +
+                `(foo/): only its creator can change it. They were skipped, not ` +
+                `synced. Re-run with --json to list them.`,
+        ];
+    }
+    const lines = [scopeExcludedWarning(count)];
+    const detail = scopeExcludedPrefixDetail(prefixSet);
+    if (detail)
+        lines.push(detail);
+    return lines;
+}
 /**
  * Resolve the `propagateDeletePolicy` for share() calls.
  *
@@ -388,6 +450,7 @@ export async function pushAll(options, deps) {
             companyUid: m.companyUid,
             shareOptions: {
                 company: m.companyUid,
+                targetSlug: slug,
                 hqRoot: options.hqRoot,
                 paths: [path.join(options.hqRoot, "companies", slug)],
                 skipUnchanged: true,
@@ -445,7 +508,13 @@ export async function pushAll(options, deps) {
             result.bytesUploaded += r.bytesUploaded;
             result.filesDeleted += r.filesDeleted;
             result.filesExcludedByScope += r.filesExcludedByScope;
-            result.perCompany.push({ slug: entry.slug, result: r });
+            result.perCompany.push({
+                slug: entry.slug,
+                result: r,
+                ...(entry.shareOptions.prefixSet !== undefined
+                    ? { prefixSet: entry.shareOptions.prefixSet }
+                    : {}),
+            });
         }
         catch (err) {
             const message = formatSyncFailure(err);
@@ -455,6 +524,24 @@ export async function pushAll(options, deps) {
     }
     return result;
 }
+/**
+ * Credentials `hq sync push` hands to share(). A pre-vended EntityContext
+ * (AppBar's `--creds-from-stdin` first push) cannot write under private
+ * folders directly, so it travels with the caller's vault config as
+ * `privateFolderVaultConfig`. share() takes exactly one of `vaultConfig` /
+ * `entityContext`.
+ */
+export function pushShareCredentials(input) {
+    if (input.entityContext) {
+        return {
+            entityContext: input.entityContext,
+            ...(input.scopeVaultConfig
+                ? { privateFolderVaultConfig: input.scopeVaultConfig }
+                : {}),
+        };
+    }
+    return input.vaultConfig ? { vaultConfig: input.vaultConfig } : {};
+}
 /**
  * Resolve the canonical person entity UID for the logged-in user. Used by
  * `hq sync {push,pull,now} --personal` to target the personal vault without
@@ -472,21 +559,15 @@ export async function resolveCanonicalPersonUid(vaultClient) {
     return pick.uid;
 }
 /**
- * Refuse `hq sync push --personal <path>` — the combination silently
- * bypasses `PERSONAL_VAULT_EXCLUDED_TOP_LEVEL` (which is only applied by
- * `computePersonalVaultPaths`), risking cross-scope upload of `companies/`,
- * `repos/`, `workspace/`, or `.git/` content to the personal vault. Real
- * incident (2026-05-21): a single command uploaded 196 `companies/{slug}/**`
- * objects to a personal vault before being killed. Cleanup required a
- * hand-rolled S3 sweep. Closes hq-cli#25.
- *
- * Refusal — not silent filtering — is intentional: explicit is better than
- * implicit guesswork, and the legitimate "I want to push a subset of my
- * personal vault" use case has a clean workaround (drop `--personal`, the
- * subset upload targets the active company via standard semantics).
+ * Keep `hq sync push --personal <path>` refused by default. Positional paths
+ * bypass `computePersonalVaultPaths` and can send excluded `companies/`,
+ * `repos/`, `workspace/`, or `.git/` content to the personal vault. The
+ * default-off targeted-paths gate allows the combination only after every
+ * path is realpath-normalized and checked against the computed personal scope
+ * and its file exclusions. Closes hq-cli#25.
  */
-export function assertNoPersonalPositionalPaths(opts, paths) {
-    if (opts.personal && paths && paths.length > 0) {
+export function assertNoPersonalPositionalPaths(opts, paths, targetedPersonalPathsEnabled = false) {
+    if (opts.personal && paths && paths.length > 0 && !targetedPersonalPathsEnabled) {
         throw new Error("`--personal` cannot be combined with explicit [paths]: " +
             "positional paths bypass the PERSONAL_VAULT_EXCLUDED_TOP_LEVEL " +
             "guard (skips .git/, companies/, repos/, workspace/), risking " +
@@ -616,6 +697,32 @@ async function resolveCliPullScope(client, companyRef, hqRoot) {
     }
     return resolvePullScope(client, companyUid, slug, hqRoot);
 }
+/**
+ * The progress-snapshot label share()'s default recorder would use: the
+ * target's slug, or null for a personal-vault push. A pre-vended context
+ * carries its slug; otherwise the caller's company reference is the best the
+ * CLI knows before share() resolves it.
+ */
+function shareProgressCompany(input) {
+    if (input.personalMode)
+        return null;
+    if (input.entityContext) {
+        return input.entityContext.uid.startsWith("prs_")
+            ? null
+            : input.entityContext.slug;
+    }
+    return input.companyRef ?? null;
+}
+/** Only a real slug builds a company billing link; a raw uid does not. */
+function companySlugForBilling(label) {
+    return label && !/^(?:cmp|prs)_/.test(label) ? { companySlug: label } : {};
+}
+/** Print one push leg's refusal block under its row. */
+function printPlanLimitRefusal(summary, indent = "    ") {
+    for (const line of renderPlanLimitRefusalLines(summary, indent)) {
+        console.log(chalk.yellow(line));
+    }
+}
 export function registerCloudCommands(program) {
     program
         .command("push")
@@ -682,7 +789,13 @@ export function registerCloudCommands(program) {
             // 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 withSyncHealthReport(() => runPushAll(options.hqRoot, options.message, options.onConflict, options.personal === false));
+            await withSyncHealthReport(async () => {
+                const refused = await runPushAll(options.hqRoot, options.message, options.onConflict, options.personal === false);
+                // A plan-limit refusal is not a sync failure, but the push did
+                // not upload everything it was asked to: exit non-zero.
+                if (refused)
+                    throw new SyncExitError(1, { health: "succeeded" });
+            });
             return;
         }
         const jsonMode = options.json === true;
@@ -698,6 +811,7 @@ export function registerCloudCommands(program) {
         // Assigned right before the sync engine runs, so option-validation
         // failures never count as a sync attempt (US-003).
         let syncHealth;
+        let explicitPersonalPaths;
         try {
             if (options.personal && options.credsFromStdin) {
                 throw new Error("`--personal` cannot be combined with --creds-from-stdin: " +
@@ -706,7 +820,11 @@ export function registerCloudCommands(program) {
                     "to have already resolved entity + credentials. Pick one.");
             }
             // Closes hq-cli#25 — see `assertNoPersonalPositionalPaths` doc-block.
-            assertNoPersonalPositionalPaths(options, paths);
+            const targetedPersonalPathsEnabled = Boolean(options.personal && paths && paths.length > 0 && personalTargetedPushPathsEnabled());
+            assertNoPersonalPositionalPaths(options, paths, targetedPersonalPathsEnabled);
+            if (targetedPersonalPathsEnabled) {
+                explicitPersonalPaths = resolveExplicitPersonalPushPaths(options.hqRoot, paths);
+            }
             log(chalk.bold("\nHQ Sync — Push"));
             log(`  HQ root:  ${options.hqRoot}`);
             // Resolve credentials. Two paths:
@@ -715,7 +833,7 @@ export function registerCloudCommands(program) {
             //   2. default: vend via cached Cognito session (the human CLI path).
             let entityContext;
             let vaultConfig;
-            /** Vault API config for membership/grant scope lookups. Set even on the pre-vended `--creds-from-stdin` path — share() accepts entityContext OR vaultConfig, not both. */
+            /** Vault API config for membership/grant scope lookups and, on the pre-vended `--creds-from-stdin` path, private-folder uploads. */
             let scopeVaultConfig;
             if (options.credsFromStdin) {
                 if (process.stdin.isTTY) {
@@ -732,11 +850,11 @@ export function registerCloudCommands(program) {
                 }
                 // Upload creds are pre-vended in entityContext, but prefix filtering
                 // still needs vault-service membership/grant resolution.
-                const accessToken = await ensureCognitoToken();
+                const accessToken = await ensureSyncCognitoToken();
                 scopeVaultConfig = buildVaultConfig(accessToken);
             }
             else {
-                const accessToken = await ensureCognitoToken();
+                const accessToken = await ensureSyncCognitoToken();
                 vaultConfig = buildVaultConfig(accessToken);
                 scopeVaultConfig = vaultConfig;
             }
@@ -764,11 +882,13 @@ export function registerCloudCommands(program) {
             // Otherwise preserve the historical "default to cwd" semantics so
             // `hq sync push <file>` and bare `hq sync push` from inside the
             // company tree both work as before.
-            const targetPaths = paths && paths.length > 0
-                ? paths
-                : options.personal
-                    ? computePersonalVaultPaths(options.hqRoot)
-                    : [process.cwd()];
+            const targetPaths = explicitPersonalPaths
+                ? explicitPersonalPaths
+                : paths && paths.length > 0
+                    ? paths
+                    : options.personal
+                        ? computePersonalVaultPaths(options.hqRoot)
+                        : [process.cwd()];
             log(`  Company:  ${options.personal
                 ? `(personal: ${targetCompany})`
                 : (options.company ?? "(from .hq/config.json or stdin)")}`);
@@ -785,33 +905,50 @@ export function registerCloudCommands(program) {
             // every row renders `—`. Resolved best-effort from the cached
             // idToken — pre-vended `--creds-from-stdin` paths still get author
             // attribution as long as the caller is logged in locally.
-            const author = resolveUploadAuthorFromCache();
+            const author = resolveUploadAuthor();
             let pushPrefixSet;
             if (!personalMode && scopeVaultConfig) {
                 const scopeClient = new VaultClient(scopeVaultConfig);
                 const scope = await resolveCliPullScope(scopeClient, targetCompany, options.hqRoot);
                 pushPrefixSet = scope?.prefixSet;
             }
+            // Collect plan-limit refusals from the runner's events through the
+            // progress-recorder seam, which (unlike onEvent) leaves share()'s own
+            // console output untouched. The snapshot label mirrors share()'s
+            // default recorder: the target slug, or null for the personal vault.
+            const progressCompany = shareProgressCompany({
+                personalMode,
+                entityContext,
+                companyRef: targetCompany ?? readActiveCompany(options.hqRoot),
+            });
+            const planLimitTracker = createPlanLimitRefusalTracker(companySlugForBilling(progressCompany));
             syncHealth = beginSyncHealthReport();
             const result = await share({
                 paths: targetPaths,
                 company: targetCompany,
                 message: options.message,
                 onConflict: options.onConflict,
-                vaultConfig,
-                entityContext,
+                ...pushShareCredentials({
+                    entityContext,
+                    vaultConfig,
+                    scopeVaultConfig,
+                }),
                 hqRoot: options.hqRoot,
                 onEvent,
+                progressRecorder: trackingProgressRecorder(planLimitTracker, progressCompany),
                 ...(personalMode ? { personalMode: true } : {}),
                 ...(journalSlug !== undefined ? { journalSlug } : {}),
                 ...(author ? { author } : {}),
                 ...(pushPrefixSet !== undefined ? { prefixSet: pushPrefixSet } : {}),
             });
+            const planLimitRefused = planLimitTracker.summary();
             if (jsonMode) {
                 // Synthetic terminal event so subprocess consumers can read final
                 // counts without summing per-file events. Distinguished from
                 // SyncProgressEvent by `type:"complete"` (not in the share()
-                // event schema — added at the CLI seam).
+                // event schema — added at the CLI seam). `planLimitRefused` is
+                // additive: present only when a plan limit refused new files, so a
+                // consumer never has to infer a refusal from the counts.
                 emitJson({
                     type: "complete",
                     filesUploaded: result.filesUploaded,
@@ -819,6 +956,7 @@ export function registerCloudCommands(program) {
                     filesSkipped: result.filesSkipped,
                     conflictPaths: result.conflictPaths,
                     aborted: result.aborted,
+                    ...(planLimitRefused ? { planLimitRefused } : {}),
                 });
             }
             if (result.aborted) {
@@ -826,13 +964,37 @@ export function registerCloudCommands(program) {
                 await syncHealth.failed();
                 process.exit(1);
             }
+            recordFirstWorkBearingSync({
+                filesUploaded: result.filesUploaded,
+                filesDeleted: result.filesDeleted,
+                aborted: result.aborted,
+            });
+            if (planLimitRefused) {
+                // Never a success line over a refusal: say what was pushed, what
+                // was refused and how to fix it, then exit non-zero. The sync
+                // itself worked, so client health records a success. `--json`
+                // callers read `planLimitRefused` on the complete event instead
+                // and keep their exit status.
+                log(chalk.yellow(`\n⚠ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ` +
+                    `${result.filesSkipped} skipped), but ${describeRefusedFiles(planLimitRefused)} ` +
+                    "refused by your plan limit."));
+                for (const line of renderPlanLimitRefusalLines(planLimitRefused)) {
+                    log(chalk.yellow(line));
+                }
+                for (const line of scopeExcludedLines(result.filesExcludedByScope, pushPrefixSet)) {
+                    log(chalk.yellow(line));
+                }
+                await syncHealth.succeeded();
+                if (!jsonMode)
+                    process.exit(1);
+                return;
+            }
             if (result.filesExcludedByScope > 0) {
                 log(chalk.yellow(`\n⚠ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ` +
                     `${result.filesSkipped} skipped, ${result.filesExcludedByScope} scope-excluded)`));
-                log(chalk.yellow(scopeExcludedWarning(result.filesExcludedByScope)));
-                const prefixDetail = scopeExcludedPrefixDetail(pushPrefixSet);
-                if (prefixDetail)
-                    log(chalk.yellow(prefixDetail));
+                for (const line of scopeExcludedLines(result.filesExcludedByScope, pushPrefixSet)) {
+                    log(chalk.yellow(line));
+                }
             }
             else {
                 log(chalk.green(`\n✓ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ${result.filesSkipped} skipped)`));
@@ -907,7 +1069,7 @@ export function registerCloudCommands(program) {
             console.log(chalk.bold("\nHQ Sync — Pull"));
             console.log(`  HQ root:  ${options.hqRoot}`);
             console.log(`  Company:  ${options.company ?? "(from .hq/config.json)"}\n`);
-            const accessToken = await ensureCognitoToken();
+            const accessToken = await ensureSyncCognitoToken();
             const vaultConfig = buildVaultConfig(accessToken);
             // US-011 (2026-05-21 fix): resolve the caller's sync-config for
             // the targeted membership BEFORE the pull, so we can (a) emit the
@@ -971,6 +1133,10 @@ export function registerCloudCommands(program) {
                 await syncHealth.failed();
                 process.exit(1);
             }
+            recordFirstWorkBearingSync({
+                filesDownloaded: result.filesDownloaded,
+                aborted: result.aborted,
+            });
             console.log(chalk.green(`\n✓ Pulled ${result.filesDownloaded} file(s) (${formatBytes(result.bytesDownloaded)}, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`));
             // Emit the hint banner after success so it appears alongside the
             // summary line. Mirrors the wiring in runPullAll and runNowSingle.
@@ -996,8 +1162,18 @@ export function registerCloudCommands(program) {
         .command("status")
         .description("Show local sync journal summary")
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
-        .action((options) => {
+        .action((options, command) => {
+        const explicitHqRoot = command.getOptionValueSource("hqRoot") === "cli";
         try {
+            const hqRoot = options.hqRoot;
+            if (explicitHqRoot) {
+                if (!fs.existsSync(hqRoot)) {
+                    throw new Error(`HQ root does not exist: ${hqRoot}`);
+                }
+                if (!fs.statSync(hqRoot).isDirectory()) {
+                    throw new Error(`HQ root is not a directory: ${hqRoot}`);
+                }
+            }
             // The engine SHARDS the journal by slug — the personal-vault fanout
             // slot, one shard per cloud company, and the legacy "personal" shard.
             // Enumerate EVERY shard the engine can write (via the engine's own
@@ -1006,13 +1182,7 @@ export function registerCloudCommands(program) {
             // looked at `sync-journal._Users_<user>_hq.json` — a slug the engine
             // never writes — and printed "No sync journal yet" right after a
             // successful sync (feedback_9fbf1f82 / feedback_46288b7b).
-            const journals = listJournals();
-            if (journals.length === 0) {
-                console.log(chalk.dim("No sync journal yet — run `hq sync now`, `hq sync push`, or `hq sync pull` to create one."));
-                console.log(chalk.dim(`  Looked in: ${getStateDir()} (sync-journal.*.json)`));
-                return;
-            }
-            const configPath = path.join(options.hqRoot, ".hq", "config.json");
+            const configPath = path.join(hqRoot, ".hq", "config.json");
             let activeCompany;
             if (fs.existsSync(configPath)) {
                 try {
@@ -1023,13 +1193,22 @@ export function registerCloudCommands(program) {
                     // ignore
                 }
             }
+            // Journals live in the machine-wide state directory, independently
+            // of the HQ content root selected for this status display.
+            const stateDir = getStateDir();
+            const journals = listJournals();
             let grandFiles = 0;
             let grandBytes = 0;
             let grandLastSync = "";
             console.log(chalk.bold("\nHQ Sync — Status"));
-            console.log(`  HQ root:        ${options.hqRoot}`);
+            console.log(`  HQ root:        ${hqRoot}`);
             console.log(`  Active company: ${activeCompany ?? chalk.dim("(none)")}`);
+            console.log(`  State dir:      ${stateDir}`);
             console.log(`  Journals:       ${journals.length}`);
+            if (journals.length === 0) {
+                console.log(chalk.dim("No sync journal yet — run `hq sync now`, `hq sync push`, or `hq sync pull` to create one."));
+                return;
+            }
             for (const j of journals) {
                 const entries = Object.entries(j.journal.files ?? {});
                 // Tombstones record removed files — exclude them from "tracked".
@@ -1194,7 +1373,7 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, for
     console.log("");
     let result;
     try {
-        const accessToken = await ensureCognitoToken();
+        const accessToken = await ensureSyncCognitoToken();
         const vaultConfig = buildVaultConfig(accessToken);
         const realClient = new VaultClient(vaultConfig);
         const adapter = {
@@ -1270,6 +1449,14 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, for
         `(${formatBytes(result.bytesDownloaded)}) across ${result.attempted} ` +
         `target(s); ${result.conflicts} conflict(s); ${errored} error(s)`;
     console.log(errored > 0 ? chalk.yellow(summary) : chalk.green(summary));
+    for (const row of result.perCompany) {
+        if (row.result && !row.error) {
+            recordFirstWorkBearingSync({
+                filesDownloaded: row.result.filesDownloaded,
+                aborted: row.result.aborted,
+            });
+        }
+    }
     if (errored > 0)
         throw new SyncExitError(1);
 }
@@ -1279,7 +1466,7 @@ export async function runPullPersonal(hqRoot, onConflict) {
     console.log(`  HQ root:  ${hqRoot}`);
     console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
     try {
-        const accessToken = await ensureCognitoToken();
+        const accessToken = await ensureSyncCognitoToken();
         const vaultConfig = buildVaultConfig(accessToken);
         const client = new VaultClient(vaultConfig);
         const personalUid = await resolveCanonicalPersonUid({
@@ -1300,6 +1487,10 @@ export async function runPullPersonal(hqRoot, onConflict) {
             throw new SyncExitError(1);
         }
         console.log(chalk.green(`\n✓ Pulled ${result.filesDownloaded} file(s) (${formatBytes(result.bytesDownloaded)}, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`));
+        recordFirstWorkBearingSync({
+            filesDownloaded: result.filesDownloaded,
+            aborted: result.aborted,
+        });
     }
     catch (err) {
         if (err instanceof SyncExitError)
@@ -1308,6 +1499,11 @@ export async function runPullPersonal(hqRoot, onConflict) {
         throw new SyncExitError(1);
     }
 }
+/**
+ * Run `push --all` and print its per-target report. Returns the files a plan
+ * limit refused across every target (null when none were), so the caller can
+ * refuse to report success; hard failures still throw {@link SyncExitError}.
+ */
 async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
     console.log(chalk.bold("\nHQ Sync — Push (all)"));
     console.log(`  HQ root:  ${hqRoot}`);
@@ -1318,10 +1514,10 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
     console.log("");
     let result;
     try {
-        const accessToken = await ensureCognitoToken();
+        const accessToken = await ensureSyncCognitoToken();
         const vaultConfig = buildVaultConfig(accessToken);
         const realClient = new VaultClient(vaultConfig);
-        const author = resolveUploadAuthorFromCache();
+        const author = resolveUploadAuthor();
         const adapter = {
             listMyMemberships: () => realClient.listMyMemberships(),
             listPersonEntities: () => realClient.entity.listByType("person"),
@@ -1342,31 +1538,39 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
         }, {
             vaultClient: adapter,
             resolveScope: (companyUid, slug) => resolvePullScope(realClient, companyUid, slug, hqRoot),
-            share: (opts) => share({
-                paths: opts.paths,
-                company: opts.company,
-                vaultConfig,
-                hqRoot: opts.hqRoot,
-                ...(opts.onConflict ? { onConflict: opts.onConflict } : {}),
-                ...(opts.personalMode !== undefined
-                    ? { personalMode: opts.personalMode }
-                    : {}),
-                ...(opts.journalSlug !== undefined
-                    ? { journalSlug: opts.journalSlug }
-                    : {}),
-                ...(opts.message !== undefined ? { message: opts.message } : {}),
-                ...(opts.skipUnchanged !== undefined
-                    ? { skipUnchanged: opts.skipUnchanged }
-                    : {}),
-                ...(opts.propagateDeletes !== undefined
-                    ? { propagateDeletes: opts.propagateDeletes }
-                    : {}),
-                ...(opts.propagateDeletePolicy !== undefined
-                    ? { propagateDeletePolicy: opts.propagateDeletePolicy }
-                    : {}),
-                ...(opts.prefixSet !== undefined ? { prefixSet: opts.prefixSet } : {}),
-                ...(author ? { author } : {}),
-            }),
+            share: async (opts) => {
+                const progressCompany = opts.personalMode
+                    ? null
+                    : (opts.targetSlug ?? opts.company);
+                const tracker = createPlanLimitRefusalTracker(companySlugForBilling(progressCompany));
+                const shareResult = await share({
+                    paths: opts.paths,
+                    company: opts.company,
+                    vaultConfig,
+                    hqRoot: opts.hqRoot,
+                    progressRecorder: trackingProgressRecorder(tracker, progressCompany),
+                    ...(opts.onConflict ? { onConflict: opts.onConflict } : {}),
+                    ...(opts.personalMode !== undefined
+                        ? { personalMode: opts.personalMode }
+                        : {}),
+                    ...(opts.journalSlug !== undefined
+                        ? { journalSlug: opts.journalSlug }
+                        : {}),
+                    ...(opts.message !== undefined ? { message: opts.message } : {}),
+                    ...(opts.skipUnchanged !== undefined
+                        ? { skipUnchanged: opts.skipUnchanged }
+                        : {}),
+                    ...(opts.propagateDeletes !== undefined
+                        ? { propagateDeletes: opts.propagateDeletes }
+                        : {}),
+                    ...(opts.propagateDeletePolicy !== undefined
+                        ? { propagateDeletePolicy: opts.propagateDeletePolicy }
+                        : {}),
+                    ...(opts.prefixSet !== undefined ? { prefixSet: opts.prefixSet } : {}),
+                    ...(author ? { author } : {}),
+                });
+                return { ...shareResult, planLimit: tracker.summary() };
+            },
         });
     }
     catch (err) {
@@ -1375,35 +1579,62 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
         // terminal sync_failure before exiting on our behalf.
         throw new SyncExitError(1);
     }
+    let refused = null;
+    let refusedTargets = 0;
     for (const row of result.perCompany) {
         if (row.error) {
             console.log(chalk.red(`  ✗ ${row.slug}: ${row.error}`));
         }
         else if (row.result) {
             const r = row.result;
-            const status = r.aborted || r.filesExcludedByScope > 0
+            const legRefused = r.planLimit ?? null;
+            const status = r.aborted || r.filesExcludedByScope > 0 || legRefused
                 ? chalk.yellow("⚠")
                 : chalk.green("✓");
             console.log(`  ${status} ${row.slug}: ${r.filesUploaded} file(s), ` +
                 `${formatBytes(r.bytesUploaded)}, ${r.filesSkipped} skipped, ` +
                 `${r.filesDeleted} deleted, ${r.filesExcludedByScope} scope-excluded, ` +
                 `${r.conflictPaths.length} conflict(s)` +
-                (r.aborted ? " — aborted" : ""));
+                (r.aborted ? " — aborted" : "") +
+                (legRefused
+                    ? ` — ${describeRefusedCount(legRefused)} refused by plan limit`
+                    : ""));
+            if (legRefused) {
+                printPlanLimitRefusal(legRefused);
+                refused = mergePlanLimitRefusals(refused, legRefused);
+                refusedTargets += 1;
+            }
         }
     }
     const errored = result.errors.length;
     const summary = `\nPushed ${result.filesUploaded} file(s) ` +
         `(${formatBytes(result.bytesUploaded)}) across ${result.attempted} ` +
         `target(s); ${result.filesDeleted} deleted; ${errored} error(s); ` +
-        `${result.filesExcludedByScope} scope-excluded`;
-    console.log(errored > 0 || result.filesExcludedByScope > 0
+        `${result.filesExcludedByScope} scope-excluded` +
+        (refusedTargets > 0
+            ? `; new files refused by a plan limit on ${refusedTargets} target(s)`
+            : "");
+    console.log(errored > 0 || result.filesExcludedByScope > 0 || refusedTargets > 0
         ? chalk.yellow(summary)
         : chalk.green(summary));
-    if (result.filesExcludedByScope > 0) {
-        console.log(chalk.yellow(scopeExcludedWarning(result.filesExcludedByScope)));
+    for (const row of result.perCompany) {
+        if (row.result && !row.error) {
+            recordFirstWorkBearingSync({
+                filesUploaded: row.result.filesUploaded,
+                filesDeleted: row.result.filesDeleted,
+                aborted: row.result.aborted,
+            });
+        }
+    }
+    for (const row of result.perCompany) {
+        const excluded = row.result?.filesExcludedByScope ?? 0;
+        for (const line of scopeExcludedLines(excluded, row.prefixSet)) {
+            console.log(chalk.yellow(`${row.slug}: ${line}`));
+        }
     }
     if (errored > 0)
         throw new SyncExitError(1);
+    return refused;
 }
 async function runNowSingle(hqRoot, company, personal, message, onConflict, modeAllOverride, forceScopeShrink) {
     console.log(chalk.bold("\nHQ Sync — Now"));
@@ -1411,9 +1642,9 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
     console.log(`  Target:   ${personal ? "(personal)" : (company ?? "(active company)")}`);
     console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
     try {
-        const accessToken = await ensureCognitoToken();
+        const accessToken = await ensureSyncCognitoToken();
         const vaultConfig = buildVaultConfig(accessToken);
-        const author = resolveUploadAuthorFromCache();
+        const author = resolveUploadAuthor();
         // Resolve the target. For --personal, look up the canonical person and
         // route paths/journal through personalMode. Otherwise use the company arg
         // (or fall back to the active company inside share()/sync()).
@@ -1421,6 +1652,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         let personalMode = false;
         let journalSlug;
         let pushPaths;
+        let pushSlug;
         if (personal) {
             const client = new VaultClient(vaultConfig);
             targetCompany = await resolveCanonicalPersonUid({
@@ -1445,6 +1677,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
                     "Use --company <slug>, --personal, or set up .hq/config.json.");
             }
             pushPaths = [path.join(hqRoot, "companies", slug)];
+            pushSlug = slug;
         }
         // Push first so the subsequent pull doesn't redownload files we were
         // about to broadcast (matches hq-sync-runner ordering).
@@ -1455,11 +1688,14 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             const pushScope = await resolveCliPullScope(scopeClient, targetCompany, hqRoot);
             nowPushPrefixSet = pushScope?.prefixSet;
         }
+        const pushProgressCompany = personalMode ? null : (pushSlug ?? null);
+        const planLimitTracker = createPlanLimitRefusalTracker(companySlugForBilling(pushProgressCompany));
         const pushResult = await share({
             paths: pushPaths,
             company: targetCompany,
             vaultConfig,
             hqRoot,
+            progressRecorder: trackingProgressRecorder(planLimitTracker, pushProgressCompany),
             skipUnchanged: true,
             propagateDeletes: true,
             propagateDeletePolicy: resolveDeletePolicy(),
@@ -1470,23 +1706,33 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             ...(author ? { author } : {}),
             ...(nowPushPrefixSet !== undefined ? { prefixSet: nowPushPrefixSet } : {}),
         });
-        const pushStatus = pushResult.aborted || pushResult.filesExcludedByScope > 0
+        const pushRefused = planLimitTracker.summary();
+        const pushStatus = pushResult.aborted || pushResult.filesExcludedByScope > 0 || pushRefused
             ? chalk.yellow("⚠")
             : chalk.green("✓");
         console.log(`    ${pushStatus} ` +
             `${pushResult.filesUploaded} uploaded, ${pushResult.filesSkipped} skipped, ` +
             `${pushResult.filesDeleted} deleted, ${pushResult.filesExcludedByScope} scope-excluded` +
-            (pushResult.aborted ? " — aborted" : ""));
+            (pushResult.aborted ? " — aborted" : "") +
+            (pushRefused
+                ? ` — ${describeRefusedCount(pushRefused)} refused by plan limit`
+                : ""));
+        if (pushRefused)
+            printPlanLimitRefusal(pushRefused, "      ");
         if (pushResult.filesExcludedByScope > 0) {
-            console.log(chalk.yellow(scopeExcludedWarning(pushResult.filesExcludedByScope)));
-            const prefixDetail = scopeExcludedPrefixDetail(nowPushPrefixSet);
-            if (prefixDetail)
-                console.log(chalk.yellow(prefixDetail));
+            for (const line of scopeExcludedLines(pushResult.filesExcludedByScope, nowPushPrefixSet)) {
+                console.log(chalk.yellow(line));
+            }
         }
         if (pushResult.aborted) {
             console.log(chalk.yellow("\n⚠ Sync now aborted on push leg; pull skipped."));
             throw new SyncExitError(1);
         }
+        recordFirstWorkBearingSync({
+            filesUploaded: pushResult.filesUploaded,
+            filesDeleted: pushResult.filesDeleted,
+            aborted: pushResult.aborted,
+        });
         // US-011: resolve membership sync-config so we can either nudge an
         // all-mode owner or refuse the pull when strict-mode is on. Skipped
         // for personal targets (personal vault has no membership row) and
@@ -1578,6 +1824,10 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             console.log(chalk.yellow("\n⚠ Sync now finished with pull leg aborted."));
             throw new SyncExitError(1);
         }
+        recordFirstWorkBearingSync({
+            filesDownloaded: pullResult.filesDownloaded,
+            aborted: pullResult.aborted,
+        });
         // Emit the hint banner after a successful pull so it appears at the
         // bottom of the summary rather than mid-stream. Size-gated: only a large
         // local folder is nudged.
@@ -1588,6 +1838,12 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
                 level: bannerLevel,
             });
         }
+        if (pushRefused) {
+            // The pull ran, but the push did not upload everything: no success line.
+            console.log(chalk.yellow(`\n⚠ Sync now finished, but ${describeRefusedFiles(pushRefused)} ` +
+                "refused by your plan limit (listed above)."));
+            throw new SyncExitError(1, { health: "succeeded" });
+        }
         console.log(chalk.green("\n✓ Sync now complete"));
     }
     catch (err) {
@@ -1609,12 +1865,22 @@ async function runNowAll(hqRoot, message, onConflict, modeAllOverride, skipPerso
     // 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, skipPersonal);
+    const refused = 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, skipPersonal, forceScopeShrink);
+    if (refused) {
+        // A plan-limit refusal does not stop the pull, but the run must not end
+        // looking like a clean sync: say so last and exit non-zero.
+        console.log(chalk.yellow(`\n⚠ Sync finished, but ${describeRefusedFiles(refused)} refused ` +
+            "by your plan limit (listed under push --all above)."));
+        if (refused.upgradeUrl) {
+            console.log(chalk.yellow(`  Upgrade: ${refused.upgradeUrl}`));
+        }
+        throw new SyncExitError(1, { health: "succeeded" });
+    }
 }
 /**
  * Best-effort read of the active company slug from `<hqRoot>/.hq/config.json`.
@@ -1668,35 +1934,4 @@ async function readAllStdin() {
     }
     return Buffer.concat(chunks).toString("utf8");
 }
-/**
- * Resolve the syncing user's `UploadAuthor` (sub + email) from the cached
- * Cognito idToken. Returns `undefined` when no tokens are cached or the
- * token is missing the required claims — share() then skips the metadata
- * stamp gracefully (not an error).
- *
- * We deliberately decode the JWT here instead of verifying it: Cognito
- * already verified at issuance, and we only use the public claims to
- * label the upload's S3 user metadata (no auth decision rides on it).
- */
-function resolveUploadAuthorFromCache() {
-    const tokens = loadCachedTokens();
-    if (!tokens?.idToken)
-        return undefined;
-    const parts = tokens.idToken.split(".");
-    if (parts.length !== 3)
-        return undefined;
-    try {
-        const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
-        const padded = payload + "=".repeat((4 - (payload.length % 4)) % 4);
-        const json = Buffer.from(padded, "base64").toString("utf-8");
-        const claims = JSON.parse(json);
-        if (claims.sub && claims.email) {
-            return { userSub: claims.sub, email: claims.email };
-        }
-        return undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 //# sourceMappingURL=cloud.js.map