@quonfig/cli 0.0.32 → 0.0.34

package/README.md

@@ -14,7 +14,7 @@ $ npm install -g @quonfig/cli
 $ qfg COMMAND
 running command...
 $ qfg (--version)
-@quonfig/cli/0.0.32 linux-x64 node-v24.4.1
+@quonfig/cli/0.0.34 linux-x64 node-v24.4.1
 $ qfg --help [COMMAND]
 USAGE
   $ qfg COMMAND
@@ -91,7 +91,7 @@ EXAMPLES
   $ qfg config-schema --json-schema    # full JSON Schema document (copy into your editor)
 ```
 
-_See code: [src/commands/config-schema.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/config-schema.ts)_
+_See code: [src/commands/config-schema.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/config-schema.ts)_
 
 ## `qfg create NAME`
 
@@ -176,7 +176,7 @@ EXAMPLES
   $ qfg set-rollout my.new.flag --environment production --true-percent 20
 ```
 
-_See code: [src/commands/create.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/create.ts)_
+_See code: [src/commands/create.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/create.ts)_
 
 ## `qfg delete NAME`
 
@@ -222,7 +222,7 @@ EXAMPLES
   $ qfg delete my.config --yes
 ```
 
-_See code: [src/commands/delete.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/delete.ts)_
+_See code: [src/commands/delete.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/delete.ts)_
 
 ## `qfg flag info [NAME]`
 
@@ -425,7 +425,7 @@ EXAMPLES
   $ qfg generate --targets node-ts -o ./dist # combine with targets
 ```
 
-_See code: [src/commands/generate.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/generate.ts)_
+_See code: [src/commands/generate.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/generate.ts)_
 
 ## `qfg generate-new-hex-key`
 
@@ -448,7 +448,7 @@ EXAMPLES
   $ qfg generate-new-hex-key
 ```
 
-_See code: [src/commands/generate-new-hex-key.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/generate-new-hex-key.ts)_
+_See code: [src/commands/generate-new-hex-key.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/generate-new-hex-key.ts)_
 
 ## `qfg get [NAME]`
 
@@ -480,7 +480,7 @@ EXAMPLES
   $ qfg get my.config.name --environment=production
 ```
 
-_See code: [src/commands/get.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/get.ts)_
+_See code: [src/commands/get.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/get.ts)_
 
 ## `qfg info [NAME]`
 
@@ -528,7 +528,7 @@ EXAMPLES
   $ qfg info my.config.name --exclude-evaluations   # skip 24h stats
 ```
 
-_See code: [src/commands/info.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/info.ts)_
+_See code: [src/commands/info.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/info.ts)_
 
 ## `qfg init [DIRECTORY]`
 
@@ -568,7 +568,7 @@ EXAMPLES
   $ qfg init --dry-run
 ```
 
-_See code: [src/commands/init.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/init.ts)_
+_See code: [src/commands/init.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/init.ts)_
 
 ## `qfg interactive`
 
@@ -598,7 +598,7 @@ EXAMPLES
   $ qfg
 ```
 
-_See code: [src/commands/interactive.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/interactive.ts)_
+_See code: [src/commands/interactive.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/interactive.ts)_
 
 ## `qfg list`
 
@@ -638,7 +638,7 @@ EXAMPLES
   $ qfg list --feature-flags
 ```
 
-_See code: [src/commands/list.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/list.ts)_
+_See code: [src/commands/list.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/list.ts)_
 
 ## `qfg log-level NAME`
 
@@ -703,7 +703,7 @@ EXAMPLES
   $ qfg log-level log-level.my-app --target=Chatty --value=INFO --environment=production
 ```
 
-_See code: [src/commands/log-level.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/log-level.ts)_
+_See code: [src/commands/log-level.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/log-level.ts)_
 
 ## `qfg login`
 
@@ -728,7 +728,7 @@ EXAMPLES
   $ qfg login --profile myprofile
 ```
 
-_See code: [src/commands/login.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/login.ts)_
+_See code: [src/commands/login.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/login.ts)_
 
 ## `qfg logout`
 
@@ -751,7 +751,7 @@ EXAMPLES
   $ qfg logout
 ```
 
-_See code: [src/commands/logout.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/logout.ts)_
+_See code: [src/commands/logout.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/logout.ts)_
 
 ## `qfg migrate`
 
@@ -805,7 +805,7 @@ EXAMPLES
   $ qfg migrate --from launch --api-key $LAUNCH_API_KEY --dir ./quonfig-repo --staging
 ```
 
-_See code: [src/commands/migrate.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/migrate.ts)_
+_See code: [src/commands/migrate.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/migrate.ts)_
 
 ## `qfg migrate doctor`
 
@@ -843,7 +843,7 @@ EXAMPLES
   $ qfg migrate doctor --json
 ```
 
-_See code: [src/commands/migrate/doctor.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/migrate/doctor.ts)_
+_See code: [src/commands/migrate/doctor.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/migrate/doctor.ts)_
 
 ## `qfg migrate my-code`
 
@@ -875,7 +875,7 @@ EXAMPLES
   $ qfg migrate my-code --dry-run
 ```
 
-_See code: [src/commands/migrate/my-code.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/migrate/my-code.ts)_
+_See code: [src/commands/migrate/my-code.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/migrate/my-code.ts)_
 
 ## `qfg migrate status`
 
@@ -906,7 +906,7 @@ EXAMPLES
   $ qfg migrate status --json
 ```
 
-_See code: [src/commands/migrate/status.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/migrate/status.ts)_
+_See code: [src/commands/migrate/status.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/migrate/status.ts)_
 
 ## `qfg override [NAME] [VALUE]`
 
@@ -961,7 +961,7 @@ EXAMPLES
   $ qfg override my.flag true --env=staging
 ```
 
-_See code: [src/commands/override.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/override.ts)_
+_See code: [src/commands/override.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/override.ts)_
 
 ## `qfg pull`
 
@@ -969,10 +969,13 @@ Clone or update a local copy of your workspace config files.
 
 ```
 USAGE
-  $ qfg pull [--json] [--interactive] [--no-color] [--verbose] [--dir <value>] [--workspace <value>]
+  $ qfg pull [--json] [--interactive] [--no-color] [--verbose] [--dir <value>] [--rebase] [--workspace
+    <value>]
 
 FLAGS
   --dir=<value>        Local directory to clone/update (defaults to QUONFIG_DIR env var)
+  --rebase             Replay local commits on top of origin/main when the two have diverged. Conflicts are surfaced via
+                       standard git markers; resolve with `git rebase --continue`.
   --workspace=<value>  Workspace ID (defaults to active profile)
 
 GLOBAL FLAGS
@@ -1005,7 +1008,7 @@ EXAMPLES
   $ qfg pull  # uses QUONFIG_DIR env var
 ```
 
-_See code: [src/commands/pull.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/pull.ts)_
+_See code: [src/commands/pull.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/pull.ts)_
 
 ## `qfg push`
 
@@ -1053,7 +1056,7 @@ EXAMPLES
   $ qfg push --dir ./our-config --yes
 ```
 
-_See code: [src/commands/push.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/push.ts)_
+_See code: [src/commands/push.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/push.ts)_
 
 ## `qfg schema NAME`
 
@@ -1091,7 +1094,7 @@ EXAMPLES
   $ qfg schema my-schema --set-json-schema=@schemas/my-schema.json --protected
 ```
 
-_See code: [src/commands/schema.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/schema.ts)_
+_See code: [src/commands/schema.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/schema.ts)_
 
 ## `qfg sdk-key`
 
@@ -1118,7 +1121,7 @@ EXAMPLES
   $ qfg sdk-key revoke <key-id>
 ```
 
-_See code: [src/commands/sdk-key.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/sdk-key.ts)_
+_See code: [src/commands/sdk-key.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/sdk-key.ts)_
 
 ## `qfg sdk-key create`
 
@@ -1150,7 +1153,7 @@ EXAMPLES
   $ qfg sdk-key create --environment staging --type browser
 ```
 
-_See code: [src/commands/sdk-key/create.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/sdk-key/create.ts)_
+_See code: [src/commands/sdk-key/create.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/sdk-key/create.ts)_
 
 ## `qfg sdk-key list`
 
@@ -1179,7 +1182,7 @@ EXAMPLES
   $ qfg sdk-key list --environment production
 ```
 
-_See code: [src/commands/sdk-key/list.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/sdk-key/list.ts)_
+_See code: [src/commands/sdk-key/list.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/sdk-key/list.ts)_
 
 ## `qfg sdk-key revoke KEYID`
 
@@ -1206,7 +1209,7 @@ EXAMPLES
   $ qfg sdk-key revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
 ```
 
-_See code: [src/commands/sdk-key/revoke.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/sdk-key/revoke.ts)_
+_See code: [src/commands/sdk-key/revoke.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/sdk-key/revoke.ts)_
 
 ## `qfg set-default [NAME]`
 
@@ -1277,7 +1280,7 @@ EXAMPLES
   $ qfg pull && qfg config-schema
 ```
 
-_See code: [src/commands/set-default.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/set-default.ts)_
+_See code: [src/commands/set-default.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/set-default.ts)_
 
 ## `qfg set-rollout [NAME]`
 
@@ -1354,7 +1357,7 @@ EXAMPLES
   $ qfg set-rollout my.variant.flag --environment production --weights "a:33,b:33,c:34" --hash-by user.id
 ```
 
-_See code: [src/commands/set-rollout.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/set-rollout.ts)_
+_See code: [src/commands/set-rollout.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/set-rollout.ts)_
 
 ## `qfg sync`
 
@@ -1386,7 +1389,7 @@ EXAMPLES
   $ qfg sync --watch --dir ./our-config --interval 30
 ```
 
-_See code: [src/commands/sync.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/sync.ts)_
+_See code: [src/commands/sync.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/sync.ts)_
 
 ## `qfg toggle [NAME]`
 
@@ -1488,7 +1491,7 @@ EXAMPLES
   $ qfg verify --json
 ```
 
-_See code: [src/commands/verify.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/verify.ts)_
+_See code: [src/commands/verify.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/verify.ts)_
 
 ## `qfg whoami`
 
@@ -1511,7 +1514,7 @@ EXAMPLES
   $ qfg whoami
 ```
 
-_See code: [src/commands/whoami.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/whoami.ts)_
+_See code: [src/commands/whoami.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/whoami.ts)_
 
 ## `qfg workspace`
 
@@ -1534,7 +1537,7 @@ EXAMPLES
   $ qfg workspace
 ```
 
-_See code: [src/commands/workspace.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/workspace.ts)_
+_See code: [src/commands/workspace.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/workspace.ts)_
 
 ## `qfg workspace bootstrap`
 
@@ -1567,7 +1570,7 @@ EXAMPLES
   $ qfg workspace bootstrap --dir ./our-config --skip-validate
 ```
 
-_See code: [src/commands/workspace/bootstrap.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/workspace/bootstrap.ts)_
+_See code: [src/commands/workspace/bootstrap.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/workspace/bootstrap.ts)_
 
 ## `qfg workspace create SLUG`
 
@@ -1601,7 +1604,7 @@ EXAMPLES
   $ qfg workspace create my-team --org 11111111-1111-1111-1111-111111111111
 ```
 
-_See code: [src/commands/workspace/create.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/workspace/create.ts)_
+_See code: [src/commands/workspace/create.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/workspace/create.ts)_
 
 ## `qfg workspace switch [SLUG]`
 
@@ -1629,7 +1632,7 @@ EXAMPLES
   $ qfg workspace switch acme/production
 ```
 
-_See code: [src/commands/workspace/switch.ts](https://github.com/quonfig/cli/blob/v0.0.32/src/commands/workspace/switch.ts)_
+_See code: [src/commands/workspace/switch.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/workspace/switch.ts)_
 <!-- commandsstop -->
 
 ## Local Development

package/dist/commands/migrate.js

@@ -4,8 +4,9 @@ import path from 'node:path';
 import { BaseCommand } from '../index.js';
 import { CrossSourceError, assertSourceMatches, readImportState } from '../migrate/import-state.js';
 import { applyLocalMigration } from '../migrate/local-write.js';
-import { PushConflictError } from '../util/clone-and-stack-push.js';
-import { pushMigrationToCloud } from '../migrate/push-to-cloud.js';
+import { buildPushConflictSuggestion } from '../migrate/migrate-suggestion.js';
+import { PushConflictError, PushHookRejectedError } from '../util/clone-and-stack-push.js';
+import { MigratorVerifyError, pushMigrationToCloud } from '../migrate/push-to-cloud.js';
 import { UnknownSourceError, getSource } from '../migrate/registry.js';
 import { NotYetImplementedError, } from '../migrate/source.js';
 import { applyLaunchBaseUrl } from '../migrate/sources/launch/api.js';
@@ -171,8 +172,16 @@ export default class Migrate extends BaseCommand {
                     };
                 }
                 catch (error) {
+                    if (error instanceof PushHookRejectedError) {
+                        return this.err(`${error.message}\n\nThe remote validation hook rejected the push. Fix the errors reported above (typically in the source system or by editing the local files in ${dir}), then re-run with --push. You can re-run \`qfg verify ${dir}\` locally to confirm the fixes before pushing.`);
+                    }
                     if (error instanceof PushConflictError) {
-                        return this.err(`${error.message}\n\nRe-run \`qfg migrate --from ${flags.from} --workspace ${workspaceId} --push\` to pick up remote changes before retrying.`);
+                        return this.err(`${error.message}\n\n${buildPushConflictSuggestion({ from: flags.from, userWorkspaceFlag: flags.workspace })}`);
+                    }
+                    if (error instanceof MigratorVerifyError) {
+                        return this.err(`${error.message}\n\nThe migrated workspace was written to ${dir} but was NOT pushed. ` +
+                            `Fix the issues above (typically in the source system or by editing the local files), then re-run with --push. ` +
+                            `You can re-run \`qfg verify ${dir}\` locally to confirm the fixes before pushing.`);
                     }
                     throw error;
                 }
@@ -213,6 +222,7 @@ export default class Migrate extends BaseCommand {
             // detectDuplicateKeys). The source accumulator holds the data regardless.
             warnAboutDroppedOverrides(this, source.getDroppedOverrides?.() ?? null);
             warnAboutSkippedConfigs(this, source.getSkippedConfigs?.() ?? null);
+            warnAboutCoercedSentinels(this, source.getCoercedSentinels?.() ?? null);
             warnAboutDuplicateResolutions(this, duplicateResolutionsForWarn);
         }
     }
@@ -283,6 +293,21 @@ function warnAboutDuplicateResolutions(cmd, resolved) {
     }
     cmd.warn('Full detail is also written to MIGRATION_REPORT.md.');
 }
+function warnAboutCoercedSentinels(cmd, coerced) {
+    if (!coerced || coerced.total === 0)
+        return;
+    const envIds = Object.keys(coerced.byEnv).sort();
+    cmd.warn(`Coerced ${coerced.total} sentinel rule value(s) from Launch's "no value set yet" sentinel ({type:"string", value:""}) to the typed default for the surrounding config. Without coercion the qfg-verify hook would reject these as type-mismatches and fail-stop the entire push:`);
+    for (const envId of envIds) {
+        const perFlag = coerced.byEnv[envId];
+        const totalForEnv = Object.values(perFlag).reduce((s, n) => s + n, 0);
+        cmd.warn(`  env-${envId}: ${totalForEnv} coerced from ${Object.keys(perFlag).length} config(s)`);
+        for (const flagPath of Object.keys(perFlag).sort()) {
+            cmd.warn(`    - ${flagPath} (${perFlag[flagPath]})`);
+        }
+    }
+    cmd.warn(`If you want a real default for these rules, set one in the source system and re-run the migration. Full detail is also written to MIGRATION_REPORT.md.`);
+}
 function warnAboutSkippedConfigs(cmd, skipped) {
     if (!skipped || skipped.total === 0)
         return;

package/dist/commands/pull.d.ts

@@ -5,6 +5,7 @@ export default class Pull extends BaseCommand {
     static examples: string[];
     static flags: {
         dir: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        rebase: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
         workspace: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
     };
     run(): Promise<JsonObj | void>;

package/dist/commands/pull.js

@@ -6,7 +6,7 @@ import { loadGiteaToken, isGiteaTokenExpired, saveGiteaToken } from '../util/git
 import { mintAndStoreGiteaReadToken, mintGiteaToken } from '../util/gitea-api.js';
 import { readWorkspaceSlug, tryParseWorkspacePin, writeWorkspaceSlug } from '../util/quonfig-json.js';
 import { resolveWorkspaceUuid } from '../util/resolve-workspace.js';
-import { isGitRepo, getRemoteUrl, gitFetch, gitSetRemote, canFastForward, hasDivergedFromRemote, gitMergeFfOnly, gitClone, displayUrl, addAndCommitFile, dirtyTrackedFiles, } from '../util/git-ops.js';
+import { isGitRepo, getRemoteUrl, gitFetch, gitSetRemote, canFastForward, hasDivergedFromRemote, gitMergeFfOnly, gitPullRebase, gitClone, displayUrl, addAndCommitFile, dirtyTrackedFiles, } from '../util/git-ops.js';
 export default class Pull extends BaseCommand {
     static description = `Clone or update a local copy of your workspace config files.
 
@@ -29,6 +29,10 @@ CLI shortcuts (no JSON editing needed for simple cases):
         dir: Flags.string({
             description: 'Local directory to clone/update (defaults to QUONFIG_DIR env var)',
         }),
+        rebase: Flags.boolean({
+            default: false,
+            description: 'Replay local commits on top of origin/main when the two have diverged. Conflicts are surfaced via standard git markers; resolve with `git rebase --continue`.',
+        }),
         workspace: Flags.string({
             description: 'Workspace ID (defaults to active profile)',
         }),
@@ -85,7 +89,43 @@ CLI shortcuts (no JSON editing needed for simple cases):
             const ff = await canFastForward(resolvedDir);
             const diverged = !ff && (await hasDivergedFromRemote(resolvedDir));
             if (diverged) {
-                return this.err('Local commits diverge from remote — resolve manually.');
+                if (flags.rebase) {
+                    this.log('Local and origin/main have diverged. Rebasing local commits on top of origin/main...');
+                    const result = await gitPullRebase(resolvedDir);
+                    if (result.kind === 'clean') {
+                        this.log(`Rebased ${result.commitsRebased} local commit(s) onto origin/main. Run \`qfg push\` to publish.`);
+                        // Fall through to post-pull work (QUONFIG_DIR write, pin backfill).
+                    }
+                    else if (result.kind === 'conflicts') {
+                        this.log('');
+                        this.log('Rebase paused with conflicts in:');
+                        for (const f of result.conflictedFiles)
+                            this.log(`  ${f}`);
+                        this.log('');
+                        this.log('To finish the rebase:');
+                        this.log(`  1. Edit each file above and pick the values you want; remove the git conflict markers.`);
+                        this.log(`  2. git -C ${resolvedDir} add <files>`);
+                        this.log(`  3. git -C ${resolvedDir} rebase --continue`);
+                        this.log(`  4. qfg push`);
+                        this.log('');
+                        this.log('To abort the rebase and try a different approach:');
+                        this.log(`  git -C ${resolvedDir} rebase --abort`);
+                        return this.err('Rebase paused on conflicts — see instructions above.');
+                    }
+                    else {
+                        return this.err(`Rebase could not start: ${result.reason}\n\n` +
+                            `Most likely the working tree has uncommitted edits. Commit or stash them, then re-run \`qfg pull --rebase\`.`);
+                    }
+                }
+                else {
+                    return this.err(`Local commits diverge from origin/main.\n\n` +
+                        `Your local branch has commits that are not on origin, and origin has commits that are not local. ` +
+                        `qfg pull will not merge automatically. Pick one:\n\n` +
+                        `  Replay your local commits on top of origin/main:\n` +
+                        `    qfg pull --rebase --dir ${resolvedDir}\n\n` +
+                        `  Discard your local commits and take origin/main as-is (LOSES local work):\n` +
+                        `    git -C ${resolvedDir} reset --hard origin/main`);
+                }
             }
             if (ff) {
                 const newCommits = await gitMergeFfOnly(resolvedDir);

package/dist/commands/push.js

@@ -3,7 +3,7 @@ import * as path from 'node:path';
 import { Flags } from '@oclif/core';
 import { BaseCommand } from '../index.js';
 import { mintGiteaToken } from '../util/gitea-api.js';
-import { getRemoteUrl, gitFetch, gitSetRemote, isGitRepo, runGit } from '../util/git-ops.js';
+import { dirtyTrackedFiles, getRemoteUrl, gitFetch, gitSetRemote, isGitRepo, isLocalBehindOrDivergedFromRemote, runGit } from '../util/git-ops.js';
 import { PushFatalError, runPush, } from '../push/run-push.js';
 import { computeBarePathDiff } from '../push/bare-path-diff.js';
 import { callConfigsPush } from '../push/config-push-client.js';
@@ -202,6 +202,29 @@ export function buildRealDeps(cmd, orgSlug) {
             const probe = await ensureBarePathProbe(dir);
             return probe.totalRemoteFiles;
         },
+        async isLocalBehindRemote(dir) {
+            // qfg-fboj: stale-HEAD guard for the clone path. Implementation
+            // lives in git-ops.ts so it can be unit-tested against a real
+            // local git repo. We still gate on isGitRepo here because the
+            // helper does not (it returns false on any error, but we want to
+            // skip the rev-parse cost on the bare path entirely).
+            if (!(await isGitRepo(dir)))
+                return false;
+            return isLocalBehindOrDivergedFromRemote(dir);
+        },
+        async dirtyTrackedFiles(dir) {
+            // qfg-fboj: surface uncommitted edits so the user sees they were
+            // not included in this push. Only meaningful on the clone path —
+            // bare path doesn't have a .git/ to status.
+            if (!(await isGitRepo(dir)))
+                return [];
+            try {
+                return await dirtyTrackedFiles(dir);
+            }
+            catch {
+                return [];
+            }
+        },
     };
     const deps = {
         async mintWriteToken(requestedTarget) {

package/dist/migrate/local-write.d.ts

@@ -1,7 +1,7 @@
 import { type ImportState } from './import-state.js';
 import { type MigrationReportData } from './migration-report.js';
 import { type PushIdentity } from '../util/clone-and-stack-push.js';
-import type { DroppedOverrideSummary, DuplicateResolutionSummary, LegacyChange, MigrationSource, SkippedConfigSummary } from './source.js';
+import type { CoercedSentinelSummary, DroppedOverrideSummary, DuplicateResolutionSummary, LegacyChange, MigrationSource, SkippedConfigSummary } from './source.js';
 export interface ApplyLocalMigrationOptions {
     /** Commit author. Defaults to the migrator identity. */
     author?: PushIdentity;
@@ -19,6 +19,8 @@ export interface ApplyLocalMigrationOptions {
 export interface ApplyLocalMigrationResult {
     /** `'initialized'` if we had to `git init` the target, `'reused'` if it was already a repo. */
     action: 'initialized' | 'reused';
+    /** Sentinel rule values coerced to typed defaults during translate. Null if none. */
+    coercedSentinels: CoercedSentinelSummary | null;
     commitSha: string | null;
     /** `false` if translate produced no net changes — nothing was committed. */
     committed: boolean;

package/dist/migrate/local-write.js

@@ -85,9 +85,11 @@ export const applyLocalMigration = async (opts) => {
     writeImportState(opts.localDir, opts.importState);
     const droppedOverrides = opts.source.getDroppedOverrides?.() ?? null;
     const skippedConfigs = opts.source.getSkippedConfigs?.() ?? null;
+    const coercedSentinels = opts.source.getCoercedSentinels?.() ?? null;
     const duplicateResolutions = resolutionEntries.length > 0 ? { entries: resolutionEntries, total: resolutionEntries.length } : null;
     const reportData = {
         ...opts.reportData,
+        ...(coercedSentinels ? { coercedSentinels } : {}),
         ...(droppedOverrides ? { droppedOverrides } : {}),
         ...(duplicateResolutions ? { duplicateResolutions } : {}),
         ...(skippedConfigs ? { skippedConfigs } : {}),
@@ -95,7 +97,15 @@ export const applyLocalMigration = async (opts) => {
     writeMigrationReport(opts.localDir, reportData);
     await runGit(['-C', opts.localDir, 'add', '--all']);
     if (!(await hasStagedChanges(opts.localDir))) {
-        return { action, committed: false, commitSha: null, droppedOverrides, duplicateResolutions, skippedConfigs };
+        return {
+            action,
+            coercedSentinels,
+            committed: false,
+            commitSha: null,
+            droppedOverrides,
+            duplicateResolutions,
+            skippedConfigs,
+        };
     }
     await spawnGit(['-C', opts.localDir, 'commit', '-F', '-'], {
         stdin: opts.commitMessage,
@@ -109,6 +119,7 @@ export const applyLocalMigration = async (opts) => {
     const { stdout: sha } = await runGit(['-C', opts.localDir, 'rev-parse', 'HEAD']);
     return {
         action,
+        coercedSentinels,
         commitSha: sha.trim(),
         committed: true,
         droppedOverrides,

package/dist/migrate/migrate-suggestion.d.ts

@@ -0,0 +1,12 @@
+export interface PushConflictSuggestionInput {
+    from: string;
+    /**
+     * The original `--workspace` flag string the user typed, e.g.
+     * `test-organization/semgrep-test-1`. Pass `undefined` if the user did not
+     * pass `--workspace` (and the command resolved the workspace via the saved
+     * profile). Never pass the resolved workspace UUID — the suggestion is meant
+     * to be a copy-paste of the user's original invocation.
+     */
+    userWorkspaceFlag: string | undefined;
+}
+export declare function buildPushConflictSuggestion({ from, userWorkspaceFlag }: PushConflictSuggestionInput): string;

package/dist/migrate/migrate-suggestion.js

@@ -0,0 +1,4 @@
+export function buildPushConflictSuggestion({ from, userWorkspaceFlag }) {
+    const workspaceArg = userWorkspaceFlag ? ` --workspace ${userWorkspaceFlag}` : '';
+    return `Re-run \`qfg migrate --from ${from}${workspaceArg} --push\` to pick up remote changes before retrying.`;
+}

package/dist/migrate/migration-report.d.ts

@@ -1,5 +1,5 @@
 import type { IdentifierMap } from './identifier-map.js';
-import type { DroppedOverrideSummary, DuplicateResolutionSummary, SkippedConfigSummary } from './source.js';
+import type { CoercedSentinelSummary, DroppedOverrideSummary, DuplicateResolutionSummary, SkippedConfigSummary } from './source.js';
 export interface MigrationReportCounts {
     environmentsMapped: number;
     flagsMigrated: number;
@@ -29,6 +29,12 @@ export interface FollowUpChecklist {
 }
 export interface MigrationReportData {
     cleanMappings: CleanMapping[];
+    /**
+     * Rule values that translate() coerced from a sentinel like Launch's
+     * empty-string "no value set yet" to the typed default. Null when nothing
+     * was coerced.
+     */
+    coercedSentinels?: CoercedSentinelSummary | null;
     counts: MigrationReportCounts;
     /**
      * Override sections that were dropped during translate() because the env.id was not

package/dist/migrate/migration-report.js

@@ -87,6 +87,27 @@ const renderDuplicateResolutions = (resolved) => {
     }
     return lines.join('\n');
 };
+const renderCoercedSentinels = (coerced) => {
+    if (!coerced || coerced.total === 0)
+        return null;
+    const envIds = Object.keys(coerced.byEnv).sort();
+    const lines = [
+        '## Coerced sentinel rule values',
+        '',
+        `Coerced **${coerced.total}** rule value(s) from Launch's "no value set yet" sentinel ({type:"string", value:""}) to the typed default for the surrounding config. The qfg-verify hook would otherwise reject these as type-mismatches and fail-stop the entire push. Affected envs: **${envIds.length}**. Review each and set a real default in the source system if needed.`,
+    ];
+    for (const envId of envIds) {
+        const perFlag = coerced.byEnv[envId];
+        const totalForEnv = Object.values(perFlag).reduce((s, n) => s + n, 0);
+        const flagCount = Object.keys(perFlag).length;
+        lines.push('', `### env-${envId} — ${totalForEnv} coerced from ${flagCount} config(s)`, '');
+        const sorted = Object.keys(perFlag).sort();
+        for (const flagPath of sorted) {
+            lines.push(`- \`${flagPath}\` (${perFlag[flagPath]})`);
+        }
+    }
+    return lines.join('\n');
+};
 const renderSkippedConfigs = (skipped) => {
     if (!skipped || skipped.total === 0)
         return null;
@@ -136,6 +157,9 @@ export const buildMigrationReport = (data) => {
     const skipped = renderSkippedConfigs(data.skippedConfigs);
     if (skipped !== null)
         sections.push(skipped);
+    const coerced = renderCoercedSentinels(data.coercedSentinels);
+    if (coerced !== null)
+        sections.push(coerced);
     sections.push(renderFollowUp(data.followUp));
     return sections.join('\n\n') + '\n';
 };

package/dist/migrate/push-to-cloud.d.ts

@@ -1,7 +1,19 @@
 import { type ImportState } from './import-state.js';
 import { type MigrationReportData } from './migration-report.js';
 import { type CloneAndStackPushResult } from '../util/clone-and-stack-push.js';
-import type { DroppedOverrideSummary, DuplicateResolutionSummary, LegacyChange, MigrationSource, SkippedConfigSummary } from './source.js';
+import { type ValidationResult } from '../verify/validate.js';
+import type { CoercedSentinelSummary, DroppedOverrideSummary, DuplicateResolutionSummary, LegacyChange, MigrationSource, SkippedConfigSummary } from './source.js';
+/**
+ * Thrown when the migrator's freshly-written workspace fails the same checks
+ * that the Gitea pre-receive `qfg-verify` hook will run server-side. We raise
+ * this client-side after `applyDelta` writes files but before commit + push,
+ * so the customer sees the failure locally rather than after a full push
+ * round-trip is rejected (qfg-52qg).
+ */
+export declare class MigratorVerifyError extends Error {
+    readonly result: ValidationResult;
+    constructor(result: ValidationResult);
+}
 export interface PushMigrationToCloudOptions {
     branch?: string;
     changes: LegacyChange[];
@@ -19,6 +31,7 @@ export interface PushMigrationToCloudOptions {
     source: MigrationSource;
 }
 export interface PushMigrationToCloudResult extends CloneAndStackPushResult {
+    coercedSentinels: CoercedSentinelSummary | null;
     droppedOverrides: DroppedOverrideSummary | null;
     duplicateResolutions: DuplicateResolutionSummary | null;
     skippedConfigs: SkippedConfigSummary | null;

package/dist/migrate/push-to-cloud.js

@@ -4,6 +4,25 @@ import { removeQfFromGitignore, writeImportState } from './import-state.js';
 import { writeMigrationReport } from './migration-report.js';
 import { detectDuplicateKeys } from './sources/launch/translate.js';
 import { cloneAndStackPush, } from '../util/clone-and-stack-push.js';
+import { formatResult, validateWorkspace } from '../verify/validate.js';
+/**
+ * Thrown when the migrator's freshly-written workspace fails the same checks
+ * that the Gitea pre-receive `qfg-verify` hook will run server-side. We raise
+ * this client-side after `applyDelta` writes files but before commit + push,
+ * so the customer sees the failure locally rather than after a full push
+ * round-trip is rejected (qfg-52qg).
+ */
+export class MigratorVerifyError extends Error {
+    result;
+    constructor(result) {
+        const errorCount = result.issues.filter((i) => i.severity === 'error').length;
+        super(`Migrator output failed qfg verify: ${errorCount} error(s) in ${result.filesChecked} file(s). ` +
+            `Refusing to push — the same errors would be rejected by the server pre-receive hook.\n\n` +
+            formatResult(result));
+        this.name = 'MigratorVerifyError';
+        this.result = result;
+    }
+}
 const writeQuonfigFiles = (dir, changes, source) => {
     const livePaths = new Map();
     for (const change of changes) {
@@ -65,6 +84,7 @@ const mergeEnvironmentsIntoQuonfigJson = (dir, sourceEnvs) => {
     fs.writeFileSync(quonfigPath, JSON.stringify({ ...existing, environments: merged }, null, 2) + '\n', 'utf8');
 };
 export const pushMigrationToCloud = async (opts) => {
+    let coercedSentinels = null;
     let droppedOverrides = null;
     let duplicateResolutions = null;
     let skippedConfigs = null;
@@ -78,15 +98,24 @@ export const pushMigrationToCloud = async (opts) => {
             writeImportState(dir, opts.importState);
             droppedOverrides = opts.source.getDroppedOverrides?.() ?? null;
             skippedConfigs = opts.source.getSkippedConfigs?.() ?? null;
+            coercedSentinels = opts.source.getCoercedSentinels?.() ?? null;
             duplicateResolutions =
                 resolutionEntries.length > 0 ? { entries: resolutionEntries, total: resolutionEntries.length } : null;
             const reportData = {
                 ...opts.reportData,
+                ...(coercedSentinels ? { coercedSentinels } : {}),
                 ...(droppedOverrides ? { droppedOverrides } : {}),
                 ...(duplicateResolutions ? { duplicateResolutions } : {}),
                 ...(skippedConfigs ? { skippedConfigs } : {}),
             };
             writeMigrationReport(dir, reportData);
+            // Pre-flight: run the same validation the Gitea pre-receive `qfg-verify`
+            // hook will run after the push lands. Failing here saves a full
+            // git-push round-trip and gives the customer a local, fixable error
+            // (qfg-52qg).
+            const verifyResult = validateWorkspace(dir);
+            if (!verifyResult.valid)
+                throw new MigratorVerifyError(verifyResult);
         },
         commitMessage: opts.commitMessage,
         localDir: opts.localDir,
@@ -95,5 +124,5 @@ export const pushMigrationToCloud = async (opts) => {
     if (opts.branch !== undefined)
         cloneOpts.branch = opts.branch;
     const result = await cloneAndStackPush(cloneOpts);
-    return { ...result, droppedOverrides, duplicateResolutions, skippedConfigs };
+    return { ...result, coercedSentinels, droppedOverrides, duplicateResolutions, skippedConfigs };
 };

package/dist/migrate/source.d.ts

@@ -17,6 +17,19 @@ export interface DroppedOverrideSummary {
     /** Total override sections dropped across every env + flag. */
     total: number;
 }
+/**
+ * qfg-gpnd: Per-config tally of rule values that were coerced from a Launch
+ * "no value set yet" sentinel ({type:'string', value:''}) to the typed default
+ * because the surrounding config valueType was non-string. Tracking is per
+ * envId (or 'default' for the default section) so customers can see which
+ * environments were affected.
+ */
+export interface CoercedSentinelSummary {
+    /** Per-envId → per-output-path count of coerced sentinel rule values. */
+    byEnv: Record<string, Record<string, number>>;
+    /** Total rule values coerced across every env + config. */
+    total: number;
+}
 export interface SkippedConfigEntry {
     /** Source key (pre-translate) that was skipped. */
     key: string;
@@ -45,6 +58,12 @@ export interface DuplicateResolutionSummary {
 }
 export interface MigrationSource {
     fetchChanges(sinceEpochMs: null | number): AsyncIterable<LegacyChange>;
+    /**
+     * Optional post-translate accumulator. Returns any rule values that translate()
+     * coerced from a sentinel like Launch's empty-string "no value set yet" to the
+     * typed default. Null when nothing was coerced.
+     */
+    getCoercedSentinels?(): CoercedSentinelSummary | null;
     /**
      * Optional post-translate accumulator. Returns any override sections that were
      * dropped during translate() calls because the env.id was not present in the

package/dist/migrate/sources/launch/translate.d.ts

@@ -11,7 +11,7 @@ export declare class InvalidSourceConfigError extends Error {
 export declare function slugify(value: string): string;
 export declare function isLegacyLogLevel(type: string): boolean;
 export declare function normalizeLogLevelKey(key: string): string;
-export declare function transformConfig(config: LaunchConfig, envIdMap: Record<string, string>, onDroppedEnv?: (envId: string) => void): Record<string, unknown>;
+export declare function transformConfig(config: LaunchConfig, envIdMap: Record<string, string>, onDroppedEnv?: (envId: string) => void, onCoercedSentinel?: (envId: string, valueType: string) => void): Record<string, unknown>;
 export declare function getOutputPath(type: string, key: string): string;
 /**
  * Walks the set of written files looking for cross-type collisions (the same

package/dist/migrate/sources/launch/translate.js

@@ -102,6 +102,30 @@ function normalizeRules(rules, configKey, path) {
         }
     }
 }
+// qfg-gpnd: Launch emits {type:'string', value:''} as a "no value set yet"
+// sentinel even when the surrounding config valueType is non-string (most
+// commonly seen on catch-all/ALWAYS_TRUE rules). The qfg-verify hook rejects
+// these as type-mismatches and fail-stops the entire push. Coerce the sentinel
+// to the typed default so the otherwise-valid config still ships, and surface
+// each coercion via the callback so the migrator can report it.
+function coerceSentinelRules(rules, valueType, onCoerced) {
+    if (!Array.isArray(rules))
+        return;
+    if (valueType === 'string')
+        return;
+    for (const rule of rules) {
+        if (!rule || typeof rule !== 'object')
+            continue;
+        const r = rule;
+        const v = r.value;
+        if (!v || typeof v !== 'object')
+            continue;
+        if (v.type === 'string' && v.value === '') {
+            r.value = zeroValue(valueType);
+            onCoerced();
+        }
+    }
+}
 function normalizeJsonValuesInConfig(out) {
     const configKey = String(out.key ?? 'unknown');
     const defaultSection = out.default;
@@ -122,7 +146,7 @@ function normalizeJsonValuesInConfig(out) {
         }
     }
 }
-export function transformConfig(config, envIdMap, onDroppedEnv) {
+export function transformConfig(config, envIdMap, onDroppedEnv, onCoercedSentinel) {
     const out = JSON.parse(JSON.stringify(config));
     delete out.changedBy;
     delete out.modifiedAt;
@@ -137,6 +161,13 @@ export function transformConfig(config, envIdMap, onDroppedEnv) {
     if (typeof out.valueType === 'string' && out.valueType.toUpperCase() === 'LOG_LEVEL_V2') {
         out.valueType = 'log_level';
     }
+    // qfg-ol8y: Launch passes through `valueType: 'not_set_value_type'` for
+    // segments where the field was never explicitly set. qfg-verify rejects
+    // that since segments must have valueType 'bool'. Segments in qfg are
+    // unconditionally boolean ("is the user in the segment?"), so force-set.
+    if (typeof out.type === 'string' && out.type.toLowerCase() === 'segment') {
+        out.valueType = 'bool';
+    }
     if (out.type === 'log_level' && typeof out.key === 'string') {
         out.key = normalizeLogLevelKey(out.key);
     }
@@ -199,6 +230,19 @@ export function transformConfig(config, envIdMap, onDroppedEnv) {
             ],
         };
     }
+    if (typeof out.valueType === 'string') {
+        const valueType = out.valueType;
+        const defaultSection = out.default;
+        if (defaultSection && Array.isArray(defaultSection.rules)) {
+            coerceSentinelRules(defaultSection.rules, valueType, () => onCoercedSentinel?.('default', valueType));
+        }
+        if (Array.isArray(out.environments)) {
+            for (const env of out.environments) {
+                const envId = typeof env.id === 'string' ? env.id : 'unknown';
+                coerceSentinelRules(env.rules, valueType, () => onCoercedSentinel?.(envId, valueType));
+            }
+        }
+    }
     normalizeJsonValuesInConfig(out);
     return out;
 }

package/dist/migrate/sources/launch.js

@@ -1,7 +1,13 @@
 import { fetchAllChangeHistory, fetchEnvironments } from './launch/api.js';
 import { InvalidSourceConfigError, getOutputPath, isLegacyLogLevel, slugify, transformConfig, } from './launch/translate.js';
 const SOURCE_NAME = 'launch';
-const state = { apiKey: null, droppedOverrides: new Map(), envIdMap: null, skippedConfigs: [] };
+const state = {
+    apiKey: null,
+    coercedSentinels: new Map(),
+    droppedOverrides: new Map(),
+    envIdMap: null,
+    skippedConfigs: [],
+};
 class MissingAuthError extends Error {
     constructor(operation) {
         super(`launch source ${operation} requires validateAuth(apiKey) to be called first (no API key configured).`);
@@ -58,6 +64,13 @@ function translateImpl(change) {
                 state.droppedOverrides.set(envId, perFlag);
             }
             perFlag.set(outputPath, (perFlag.get(outputPath) ?? 0) + 1);
+        }, (envId) => {
+            let perFlag = state.coercedSentinels.get(envId);
+            if (!perFlag) {
+                perFlag = new Map();
+                state.coercedSentinels.set(envId, perFlag);
+            }
+            perFlag.set(outputPath, (perFlag.get(outputPath) ?? 0) + 1);
         });
     }
     catch (error) {
@@ -85,6 +98,22 @@ function getDroppedOverridesImpl() {
     }
     return { byEnv, total };
 }
+function getCoercedSentinelsImpl() {
+    if (state.coercedSentinels.size === 0)
+        return null;
+    const byEnv = {};
+    let total = 0;
+    for (const envId of [...state.coercedSentinels.keys()].sort()) {
+        const perFlag = state.coercedSentinels.get(envId);
+        const record = {};
+        for (const [flagPath, count] of [...perFlag.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+            record[flagPath] = count;
+            total += count;
+        }
+        byEnv[envId] = record;
+    }
+    return { byEnv, total };
+}
 function getSkippedConfigsImpl() {
     if (state.skippedConfigs.length === 0)
         return null;
@@ -95,11 +124,13 @@ async function validateAuthImpl(apiKey) {
     state.apiKey = apiKey;
     state.droppedOverrides = new Map();
     state.skippedConfigs = [];
+    state.coercedSentinels = new Map();
 }
 export const launchSource = {
     fetchChanges(sinceEpochMs) {
         return fetchChangesImpl(sinceEpochMs);
     },
+    getCoercedSentinels: getCoercedSentinelsImpl,
     getDroppedOverrides: getDroppedOverridesImpl,
     getSkippedConfigs: getSkippedConfigsImpl,
     listEnvironments: listEnvironmentsImpl,
@@ -112,4 +143,5 @@ export function __resetLaunchSourceForTests() {
     state.envIdMap = null;
     state.droppedOverrides = new Map();
     state.skippedConfigs = [];
+    state.coercedSentinels = new Map();
 }

package/dist/push/run-push.d.ts

@@ -42,6 +42,23 @@ export interface GitOps {
     getRemoteOriginUrl(dir: string): Promise<string | undefined>;
     /** Returns true if the dir has a `.git/` (worktree or repo). */
     isGitRepo(dir: string): Promise<boolean>;
+    /**
+     * Returns true if origin/main has commits the local HEAD does not have
+     * (local strictly behind, or diverged). False when local is up-to-date
+     * or strictly ahead of origin/main, or when origin/main is unknown.
+     *
+     * The clone-path stale-HEAD guard (qfg-fboj) refuses to push in either
+     * "behind" or "diverged" state because both produce a diff that ships
+     * REVERSAL deltas to the server, silently undoing remote-newer commits.
+     */
+    isLocalBehindRemote(dir: string): Promise<boolean>;
+    /**
+     * Tracked files (relative paths) with working-tree or staged changes.
+     * Used by the clone-path dirty-tree warning to surface uncommitted
+     * edits the user may believe are being pushed (qfg-fboj). Untracked
+     * files are excluded — same rule as `dirtyTrackedFiles` in git-ops.ts.
+     */
+    dirtyTrackedFiles(dir: string): Promise<string[]>;
     /** Set origin to `url` (add if missing, set-url if present). */
     setRemoteOrigin(dir: string, url: string): Promise<void>;
 }

package/dist/push/run-push.js

@@ -136,6 +136,15 @@ export async function runPush(input, deps) {
         await deps.gitOps.setRemoteOrigin(input.dir, backend.repoUrl);
         log('Fetching from remote...');
         await deps.gitOps.fetch(input.dir);
+        // Guard 4 (qfg-fboj): refuse to push when local HEAD is behind or has
+        // diverged from origin/main. Without this guard the HEAD-vs-origin
+        // diff produces REVERSAL deltas that silently undo whatever was
+        // committed to the cloud since the user last pulled. Tell the user
+        // to run `qfg pull` first; the standalone `--ff-only` step keeps
+        // push from doing surprising merges on the user's behalf.
+        if (await deps.gitOps.isLocalBehindRemote(input.dir)) {
+            throw new PushFatalError('Local HEAD is behind origin/main. Run `qfg pull` first to merge remote changes, then re-run `qfg push`.', 'STALE_HEAD');
+        }
         // Migration cleanup (qfg-0fn): older `qfg pull` runs wrote the
         // workspace pin to the working tree without committing. The next
         // diff would miss it. Sweep up that legacy state IF the only dirty
@@ -153,6 +162,27 @@ export async function runPush(input, deps) {
         catch {
             /* non-fatal */
         }
+        // Guard 5 (qfg-fboj): warn loudly about any tracked file with
+        // uncommitted edits beyond the workspace pin. The clone path pushes
+        // HEAD content, not the working tree, so these edits are silently
+        // dropped from the push. Listing them in the log gives the user a
+        // chance to ctrl-C, commit, and retry instead of believing they
+        // shipped what's on disk. Untracked files are intentionally not
+        // included — same rule as dirtyTrackedFiles in git-ops.ts.
+        try {
+            const dirty = await deps.gitOps.dirtyTrackedFiles(input.dir);
+            const noisyDirty = dirty.filter((f) => f !== 'quonfig.json');
+            if (noisyDirty.length > 0) {
+                log('');
+                log('Warning: working tree has uncommitted changes that will NOT be included in this push:');
+                for (const f of noisyDirty)
+                    log(`  ${f}`);
+                log('Commit them with `git add` + `git commit` and re-run `qfg push` if you meant to ship them.');
+            }
+        }
+        catch {
+            /* non-fatal */
+        }
     }
     const deltas = await deps.gitOps.diffHeadVsOrigin(input.dir);
     const totalFilesInRemote = await deps.gitOps.countFilesInRemote(input.dir);

package/dist/util/clone-and-stack-push.d.ts

@@ -31,4 +31,7 @@ export interface CloneAndStackPushResult {
 export declare class PushConflictError extends Error {
     constructor(message: string);
 }
+export declare class PushHookRejectedError extends Error {
+    constructor(message: string);
+}
 export declare const cloneAndStackPush: (opts: CloneAndStackPushOptions) => Promise<CloneAndStackPushResult>;

package/dist/util/clone-and-stack-push.js

@@ -12,6 +12,12 @@ export class PushConflictError extends Error {
         this.name = 'PushConflictError';
     }
 }
+export class PushHookRejectedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PushHookRejectedError';
+    }
+}
 const runGit = async (cwd, args) => {
     try {
         return await runGitSafe(args, { cwd });
@@ -103,8 +109,15 @@ export const cloneAndStackPush = async (opts) => {
         const e = error;
         const stderr = e.stderr ?? '';
         const combined = `${e.message}\n${stderr}`;
+        const detail = redactToken(stderr || e.message);
+        // Pre-receive / update hook rejections are functionally distinct from fast-forward
+        // conflicts: nothing the user can do by re-fetching will help. Route them to a
+        // different lead-in so the hook output (e.g. qfg-verify FAILED ...) is the call to action.
+        if (/hook declined|\[remote rejected]/i.test(combined)) {
+            throw new PushHookRejectedError(`Push to origin/${branch} was rejected by the remote validation hook. Fix the errors below and push again. Original git error:\n${detail}`);
+        }
         if (/non-fast-forward|fetch first|rejected/i.test(combined)) {
-            throw new PushConflictError(`Push to origin/${branch} was rejected: the remote has changes we do not have locally. Re-run the migrator to pick up those changes, then push again. Original git error:\n${redactToken(stderr || e.message)}`);
+            throw new PushConflictError(`Push to origin/${branch} was rejected: the remote has changes we do not have locally. Re-run the migrator to pick up those changes, then push again. Original git error:\n${detail}`);
         }
         throw error;
     }

package/dist/util/git-ops.d.ts

@@ -101,6 +101,20 @@ export declare const gitFetch: (dir: string) => Promise<void>;
  * Returns true if origin/main has commits that can be fast-forwarded into the local branch.
  */
 export declare const canFastForward: (dir: string) => Promise<boolean>;
+/**
+ * Returns true iff origin/main is NOT an ancestor of the local HEAD —
+ * covering both "local strictly behind" and "diverged" in one boolean.
+ *
+ * Used by the clone-path stale-HEAD guard in `qfg push` (qfg-fboj):
+ * either of those two states would otherwise produce a `HEAD..origin/main`
+ * diff that ships REVERSAL deltas to the server, silently undoing
+ * remote-newer commits. Both must refuse.
+ *
+ * Returns false on any git failure (no `origin/main` ref yet, no `.git/`,
+ * etc.) so the caller falls through to its other guards rather than
+ * aborting on an opaque error.
+ */
+export declare const isLocalBehindOrDivergedFromRemote: (dir: string) => Promise<boolean>;
 /**
  * Returns true if local has commits not reachable from origin/main (diverged).
  */
@@ -120,3 +134,29 @@ export declare const hasAtLeastOneCommit: (dir: string) => Promise<boolean>;
  * Get the URL stripped of credentials for display purposes.
  */
 export declare const displayUrl: (url: string) => string;
+/**
+ * Outcome of `gitPullRebase`. Three branches the caller MUST distinguish
+ * — silent failure here is what made qfg-4tey a P1 (qfg pull exit 0 with
+ * no recovery path).
+ */
+export type GitPullRebaseResult = {
+    kind: 'clean';
+    commitsRebased: number;
+} | {
+    kind: 'conflicts';
+    conflictedFiles: string[];
+} | {
+    kind: 'failed';
+    reason: string;
+};
+/**
+ * `git pull --rebase origin main`. Replays local commits on top of the
+ * remote tip. On conflicts, leaves the repo in rebase-in-progress state
+ * with `<<<<<<<` / `=======` / `>>>>>>>` markers planted by git so the
+ * user can resolve via standard git tools (`git rebase --continue` /
+ * `git rebase --abort`).
+ *
+ * Caller is responsible for surfacing recovery instructions; this function
+ * only reports the outcome.
+ */
+export declare const gitPullRebase: (dir: string) => Promise<GitPullRebaseResult>;

package/dist/util/git-ops.js

@@ -222,6 +222,41 @@ export const canFastForward = async (dir) => {
         return false;
     }
 };
+/**
+ * Returns true iff origin/main is NOT an ancestor of the local HEAD —
+ * covering both "local strictly behind" and "diverged" in one boolean.
+ *
+ * Used by the clone-path stale-HEAD guard in `qfg push` (qfg-fboj):
+ * either of those two states would otherwise produce a `HEAD..origin/main`
+ * diff that ships REVERSAL deltas to the server, silently undoing
+ * remote-newer commits. Both must refuse.
+ *
+ * Returns false on any git failure (no `origin/main` ref yet, no `.git/`,
+ * etc.) so the caller falls through to its other guards rather than
+ * aborting on an opaque error.
+ */
+export const isLocalBehindOrDivergedFromRemote = async (dir) => {
+    try {
+        const { stdout: localSha } = await runGit(['-C', dir, 'rev-parse', 'HEAD']);
+        const { stdout: remoteSha } = await runGit(['-C', dir, 'rev-parse', 'origin/main']);
+        const local = localSha.trim();
+        const remote = remoteSha.trim();
+        if (local === remote)
+            return false;
+        try {
+            // exit 0 → remote is an ancestor of local → local is strictly ahead, fine.
+            await runGit(['-C', dir, 'merge-base', '--is-ancestor', remote, local]);
+            return false;
+        }
+        catch {
+            // non-zero exit → remote is NOT an ancestor → behind or diverged.
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+};
 /**
  * Returns true if local has commits not reachable from origin/main (diverged).
  */
@@ -310,3 +345,50 @@ export const hasAtLeastOneCommit = async (dir) => {
  * Get the URL stripped of credentials for display purposes.
  */
 export const displayUrl = (url) => redactToken(url);
+/**
+ * `git pull --rebase origin main`. Replays local commits on top of the
+ * remote tip. On conflicts, leaves the repo in rebase-in-progress state
+ * with `<<<<<<<` / `=======` / `>>>>>>>` markers planted by git so the
+ * user can resolve via standard git tools (`git rebase --continue` /
+ * `git rebase --abort`).
+ *
+ * Caller is responsible for surfacing recovery instructions; this function
+ * only reports the outcome.
+ */
+export const gitPullRebase = async (dir) => {
+    // Count local-only commits BEFORE the rebase so the success path can
+    // tell the user how many got moved. After a clean rebase, origin/main
+    // is the merge-base and ahead-count == commits-rebased.
+    let commitsRebased = 0;
+    try {
+        const { stdout } = await runGit(['-C', dir, 'rev-list', '--count', 'origin/main..HEAD']);
+        commitsRebased = Number.parseInt(stdout.trim(), 10) || 0;
+    }
+    catch {
+        // Non-fatal — counting is for UX, not correctness.
+    }
+    try {
+        await runGit(['-C', dir, 'pull', '--rebase', 'origin', 'main']);
+        return { kind: 'clean', commitsRebased };
+    }
+    catch (err) {
+        // Distinguish "rebase paused on conflicts" from "rebase never started".
+        // Conflicts: `diff --diff-filter=U` lists the unmerged paths and
+        // `.git/rebase-merge/` is present.
+        try {
+            const { stdout } = await runGit(['-C', dir, 'diff', '--name-only', '--diff-filter=U']);
+            const conflictedFiles = stdout
+                .split('\n')
+                .map((s) => s.trim())
+                .filter(Boolean);
+            if (conflictedFiles.length > 0) {
+                return { kind: 'conflicts', conflictedFiles };
+            }
+        }
+        catch {
+            // Fall through to 'failed' — diff itself errored.
+        }
+        const reason = err instanceof Error ? err.message : String(err);
+        return { kind: 'failed', reason };
+    }
+};

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "0.0.32";
+declare const _default: "0.0.34";
 export default _default;

package/dist/version.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED from package.json by scripts/generate-version.mjs — do not edit.
-export default '0.0.32';
+export default '0.0.34';

package/oclif.manifest.json

@@ -1415,6 +1415,12 @@
           "multiple": false,
           "type": "option"
         },
+        "rebase": {
+          "description": "Replay local commits on top of origin/main when the two have diverged. Conflicts are surfaced via standard git markers; resolve with `git rebase --continue`.",
+          "name": "rebase",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "workspace": {
           "description": "Workspace ID (defaults to active profile)",
           "name": "workspace",
@@ -2910,5 +2916,5 @@
       ]
     }
   },
-  "version": "0.0.32"
+  "version": "0.0.34"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "packageManager": "yarn@4.11.0+sha512.4e54aeace9141df2f0177c266b05ec50dc044638157dae128c471ba65994ac802122d7ab35bcd9e81641228b7dcf24867d28e750e0bcae8a05277d600008ad54",
   "name": "@quonfig/cli",
-  "version": "0.0.32",
+  "version": "0.0.34",
   "bugs": {
     "url": "https://github.com/quonfig/cli/issues"
   },