uniweb 1.7.4 → 1.8.1

package/src/commands/push.js

@@ -95,6 +95,9 @@ import {
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
   dropSiteBoundValues,
+  untakenBase,
+  unsettledFiles,
+  holdUnchangedPush,
   pushSyncPackages
 } from '../backend/site-sync.js'
 import { resolveWorkspace, describeWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
@@ -209,6 +212,26 @@ export async function push(args = [], deps = {}) {
     }
   }
 
+  // ⛔ A GATED PUSH CLAIMS A BASE ONLY WHILE THE FILES HOLD IT (`untakenBase`) — said before
+  // anything reaches the backend, the foundation's release included. A dry run previews it;
+  // `-o` reaches no backend, and `--force` drops the gate. ⛔ *Until 2026-10-17 it ran after
+  // the bring-along, so a refused push could release a local foundation first.*
+  // ⛔ Never a file in conflict — whatever the flags (`unsettledFiles`).
+  const unsettled = unsettledFiles(siteDir)
+  if (unsettled) {
+    error(unsettled.headline)
+    for (const line of unsettled.lines) note(line)
+    return { exitCode: 1 }
+  }
+  if (!output && !force) {
+    const untaken = untakenBase(siteDir, client.origin)
+    if (untaken) {
+      error(untaken.headline)
+      for (const line of untaken.lines) note(line)
+      return { exitCode: 1 }
+    }
+  }
+
   // ⚠️ Logged in to a backend where this project has no site, while it has one
   // elsewhere: following the login CREATES a second site. Say so before the owner
   // question, which otherwise arrives with no reason attached. Not for `-o` (nothing is
@@ -601,6 +624,9 @@ export async function push(args = [], deps = {}) {
     success(
       `Nothing to push — ${skipped} entit${skipped === 1 ? 'y' : 'ies'} unchanged since the last push.`
     )
+    // ⭐ And so the backend holds what this commit sends: it is where the next pull merges
+    // from (`holdUnchangedPush`). Not for a preview, which keeps nothing.
+    if (!output && !dryRun) holdUnchangedPush(siteDir, client.origin)
     return { exitCode: 0 }
   }
   if (siteContent)

package/src/commands/refresh.js

@@ -17,17 +17,16 @@
  * which is the whole point of a start-of-day command. A version that also pushed
  * would be one you had to think about first, and so one people would stop running.
  *
- * Order is deliberate: git first, then the backend. Teammates' commits are then in
- * the files when the backend's content arrives, and `pull --merge` merges a
- * teammate's change to a file the last pull wrote just as it merges your own edits:
- * against the version that pull wrote, found in the repo's history (`pull.js`,
- * `captureLocalWork`). And if git itself conflicts, refresh stops there — one source
- * of conflict at a time.
+ * Order is deliberate: git first, then the backend. Teammates' commits — and the sync
+ * points their pulls merged — are then in the history when the backend's content
+ * arrives, so the pull merges against the newest state of the site this history shares
+ * with the backend (`utils/sync-point.js`), and a teammate's change is merged like your
+ * own. And if git itself conflicts, refresh stops there — one source of conflict at a
+ * time.
  *
- * ⛔ Until 2026-10-16 this said the merge's ancestor was the COMMITTED version of each
- * file, so taking teammates' commits first made it fresher. That was HEAD — the rule
- * `pull --merge` dropped on 2026-09-23, because HEAD stops being the version a pull
- * wrote the moment an edit is committed on top of it.
+ * ⛔ Until 2026-10-17 the merge's ancestor was what this copy's last pull wrote, per file,
+ * from a per-machine record — so a teammate's committed work outside that record was
+ * overwritten or pruned, and a fresh clone's was all outside it.
  *
  * Exits NON-ZERO when a merge left conflicts, the way a conflicted `git merge`
  * does. That is what makes `uniweb refresh && uniweb push` correct by
@@ -35,7 +34,7 @@
  * content. If a `sync` verb is ever wanted, it is that chain.
  *
  * Usage:
- *   uniweb refresh                 git pull, then merge the backend's content
+ *   uniweb refresh                 git pull, then pull: merge the backend's content
  *   uniweb refresh --no-git        skip the git remote; backend only
  *   uniweb refresh --no-backend    skip the backend; git only
  *
@@ -99,7 +98,7 @@ function siteContentUuid(siteDir, backend) {
 export async function refresh(args = [], deps = {}) {
   // An unrecognized flag is invisible to a literal scan, so it silently keeps the
   // default — a mistyped `--no-git` would still pull from the git remote. And this is
-  // the only check refresh's argv gets: the pull it runs is handed `--merge` alone
+  // the only check refresh's argv gets: the pull it runs is handed nothing of it
   // (below). A backend flag or `--token` is refused here too, naming `uniweb login`
   // (`utils/flag-guard.js`). *(This explained the check by a mistyped `--backend`
   // until 2026-10-16; the verb has taken no backend flag since 2026-09-21.)*
@@ -138,7 +137,7 @@ export async function refresh(args = [], deps = {}) {
     say.info('Pulling from the git remote…')
     const r = pullRemote(siteDir)
     if (!r.ok) {
-      say.err('git pull failed — resolve this before continuing.')
+      say.err(r.conflicts ? 'git pull left conflicts — settle them before continuing.' : 'git pull failed — resolve this before continuing.')
       for (const line of r.message.split('\n').slice(0, 6)) say.dim(line)
       // Deliberately stop. Layering the backend's content on top of an unresolved
       // git state gives the user two independent conflicts at once, and no clear
@@ -164,11 +163,11 @@ export async function refresh(args = [], deps = {}) {
   } else {
     say.info("Merging the backend's content…")
     const pull = deps.pull || (await import('./pull.js')).pull
-    // `--merge` rather than a plain pull: an author editing a different part of the
-    // same section is not a conflict, and should not be presented as one.
-    // Nothing of refresh's own argv is forwarded: the pull goes to the backend you are
-    // logged in to, as refresh does, and authenticates the same way.
-    const res = await pull(['--merge'])
+    // A pull merges: an author editing a different part of the same section is not a
+    // conflict, and is not presented as one. Nothing of refresh's own argv is forwarded:
+    // the pull goes to the backend you are logged in to, as refresh does, and
+    // authenticates the same way.
+    const res = await pull([])
     conflicts = res?.merge?.conflicted?.length ?? 0
     if (res?.exitCode && !conflicts) {
       // Failed for a reason other than conflicts — say so plainly rather than

package/src/framework-index.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-17T17:49:32.100Z",
+  "generatedAt": "2026-10-17T22:35:38.030Z",
   "packages": {
     "@uniweb/api": {
-      "version": "1.4.0"
+      "version": "1.5.0"
     },
     "@uniweb/build": {
-      "version": "1.3.9"
+      "version": "1.3.10"
     },
     "@uniweb/content-reader": {
       "version": "1.4.0"
@@ -24,7 +24,7 @@
       "version": "1.0.3"
     },
     "@uniweb/kit": {
-      "version": "1.2.4"
+      "version": "1.2.5"
     },
     "@uniweb/loom": {
       "version": "1.1.0"
@@ -42,7 +42,7 @@
       "version": "1.0.1"
     },
     "@uniweb/schemas": {
-      "version": "1.3.1"
+      "version": "1.4.0"
     },
     "@uniweb/scholar": {
       "version": "1.1.0"

package/src/index.js

@@ -74,6 +74,7 @@ import {
 } from './utils/interactive.js'
 import { findWorkspaceRoot } from './utils/workspace.js'
 import { exitWhenDrained } from './utils/exit.js'
+import { isGitRepo } from './utils/git.js'
 
 // Colors for terminal output
 const colors = {
@@ -1327,17 +1328,10 @@ async function main() {
 
   // Initialize git repository
   if (!noGit) {
-    // Skip git init if already inside a git repo (common for monorepos/workspaces)
-    let insideGitRepo = false
-    try {
-      execSync('git rev-parse --is-inside-work-tree', {
-        cwd: projectDir,
-        stdio: 'ignore'
-      })
-      insideGitRepo = true
-    } catch {
-      // Not inside a git repo — proceed with init
-    }
+    // Skip git init if a repository already holds the project (common for
+    // monorepos/workspaces). ⛔ Not one that ignores its folder: that repository can never
+    // hold its history, so the project gets its own (`isGitRepo`, the one rule).
+    const insideGitRepo = isGitRepo(projectDir)
 
     if (insideGitRepo) {
       log(
@@ -1870,7 +1864,8 @@ ${colors.bright}Usage:${colors.reset}
 A developer on a synced site has TWO external sources: the git remote (teammates'
 commits) and the backend (content authors' edits in the app). Run only \`git pull\`
 and you miss every app edit; run only \`uniweb pull\` and you miss your teammates.
-This does both — git first, then \`pull --merge\`.
+This does both — git first (merging, never rebasing), then \`uniweb pull\`, which in
+a repository merges the backend's content with yours.
 
 ${colors.bright}READ-ONLY.${colors.reset} It never pushes and cannot ship anything, so it is safe to run
 reflexively. Exits non-zero if a merge leaves conflicts.
@@ -1879,9 +1874,9 @@ ${colors.bright}Options:${colors.reset}
   --no-git           Skip the git remote; backend only
   --no-backend       Skip the backend; git only
 
-\`--force\` and \`--merge\` are NOT accepted here: this verb builds the delegated
-pull's arguments itself, and to pull \`--force\` means "discard my local work".
-Use \`uniweb sync\` when you also mean to share.
+\`--force\` is NOT accepted here: this verb builds the delegated pull's arguments
+itself, and to pull \`--force\` means "discard my local work". Use \`uniweb sync\`
+when you also mean to share.
 `,
     sync: `
 ${colors.cyan}${colors.bright}uniweb sync${colors.reset} ${colors.dim}— Catch up, then share${colors.reset}

package/src/utils/flag-guard.js

@@ -77,7 +77,7 @@ const VERBS = {
     '--no-validate', '--yes', '--no-verify', '--no-release', '--bump', ...VIA_DEPLOY
   ],
   pull: [
-    '--content-only', '--dry-run', '--force', '--merge',
+    '--content-only', '--dry-run', '--force',
     '--no-assets',
     '--no-records', '--no-delete', '--no-prune',
     // via backend/site-sync.js (the owner resolver) and utils/conformance.js
@@ -85,7 +85,7 @@ const VERBS = {
   ],
   clone: [
     '--content-only', '--no-assets', '--no-records', '--path',
-    '--project', '--org', '--personal'
+    '--project', '--org', '--personal', '--no-git'
   ],
   register: [
     '--dry-run', '--json', '--output', '-o',
@@ -113,13 +113,12 @@ const VERBS = {
     '--no-release', '--bump', ...VIA_DEPLOY
   ],
   /**
-   * `refresh` = `git pull`, then a DELEGATED `pull --merge`.
+   * `refresh` = `git pull`, then a DELEGATED `pull`.
    *
-   * It forwards nothing of its own argv to that pull — it builds `['--merge']`
-   * itself. So pull's own flags (`--merge`, `--force`, `--no-delete`, `--no-prune`,
-   * `--content-only`, …) are NOT reachable from a `refresh` argv and
-   * are deliberately absent here. ⚠️ `--force` especially: `refresh` is read-only by
-   * design, and forwarding it would ask pull to DISCARD local work.
+   * It forwards nothing of its own argv to that pull. So pull's own flags (`--force`,
+   * `--no-delete`, `--no-prune`, `--content-only`, …) are NOT reachable from a `refresh`
+   * argv and are deliberately absent here. ⚠️ `--force` especially: `refresh` is
+   * read-only by design, and forwarding it would ask pull to DISCARD local work.
    *
    * The trailing group is inert on this verb but reachable through the
    * `resolveSiteDir` / `probeUnpushed` imports — listed rather than filtered, per
@@ -238,6 +237,19 @@ export function checkFlags(verb, args = []) {
       message: `\`--as-org\` is retired — use \`--org @org\` (e.g. \`uniweb ${verb} --org @acme\`).`
     }
   }
+  // ⭐ `pull --merge` is RETIRED (2026-10-17): in a repository a pull always merges — from the
+  // newest sync point the history holds (`utils/sync-point.js`) — and outside one there is
+  // nothing to merge against.
+  if (flag === '--merge' && verb === 'pull') {
+    return {
+      flag,
+      suggestion: null,
+      message: [
+        '`uniweb pull` has no `--merge`: in a git repository a pull always merges.',
+        '  Run `uniweb pull`. Outside git it takes the backend\'s version, asking first.'
+      ].join('\n')
+    }
+  }
   const suggestion = didYouMean(flag, all)
   const lines = [`Unknown flag \`${flag}\` for \`uniweb ${verb}\`.`]
   if (suggestion) lines.push(`  Did you mean \`${suggestion}\`?`)

package/src/utils/git.js

@@ -7,30 +7,34 @@
  * already solves better.
  *
  * DETECTED, NEVER REQUIRED. A project may legitimately have no repo, and — more
- * commonly — may live *inside* a larger one: `uniweb create` already skips
- * `git init` when it finds itself inside a work tree ("common for
- * monorepos/workspaces"), and whole scopes of real projects are versioned by a
- * parent repo rather than being repo roots themselves. So the question is never
- * "is this directory a git root" but "is this path tracked by some repo", which is
- * the question git itself answers. Callers degrade to an explicit confirmation
- * when the answer is no; sync already requires an account, and a second hard
- * dependency for a safety net we can provide anyway is a bad trade.
+ * commonly — may live *inside* a larger one: `uniweb create` skips `git init` when a
+ * repository already holds it ("common for monorepos/workspaces"), and whole scopes of
+ * real projects are versioned by a parent repo rather than being repo roots
+ * themselves. So the question is never "is this directory a git root" but "does a
+ * repository HOLD this path": is it inside a work tree, in a folder that repository
+ * does not ignore. One rule answers it, `repoOf` in `utils/sync-point.js`. Outside
+ * one a pull checks out, asking first; in one it merges.
+ *
+ * ⛔ Until 2026-10-17 this said "is this path tracked by some repo" while the check
+ * was `git rev-parse --is-inside-work-tree` alone. That reads as if a folder the
+ * repository ignores were outside it, and it was not: a harness's ignored scratch
+ * project counted as inside the harness, so `refresh` ran `git pull` on the harness.
  */
 
 import { execFileSync } from 'node:child_process'
-import { createHash } from 'node:crypto'
-import { readFileSync, realpathSync } from 'node:fs'
-import { join, relative } from 'node:path'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
 import yaml from 'js-yaml'
+import { repoOf } from './sync-point.js'
 
 /**
  * The files and directories `uniweb pull` writes into.
  *
- * ONE definition, shared by the guard that blocks a pull and the message that
- * tells someone how to recover from a refused push — a second copy would drift,
- * and a stale list here means either a guard that misses or advice that is wrong.
- * `paths:` can relocate the content roots, so the local site.yml is consulted
- * rather than assuming the defaults.
+ * ONE definition, shared by the guard that stops a pull outside git and the merge a
+ * pull makes in a repository, whose sync points hold exactly these (and `public/`, where
+ * the media land) — a second copy would drift, and a stale list here means a guard that
+ * misses or a merge that drops a file. `paths:` can relocate the content roots, so the
+ * local site.yml is consulted rather than assuming the defaults.
  */
 export function siteContentRoots(siteDir) {
   // ⚠️ `queries.yml` IS AT THE SITE ROOT, and that is why it must be named here.
@@ -62,12 +66,6 @@ export function siteContentRoots(siteDir) {
   return [...roots]
 }
 
-/** Is there uncommitted work where a pull would write? False outside a repo. */
-export function hasUncommittedContent(siteDir) {
-  const dirty = uncommittedUnder(siteDir, siteContentRoots(siteDir))
-  return Array.isArray(dirty) && dirty.length > 0
-}
-
 function git(args, cwd) {
   return execFileSync('git', args, {
     cwd,
@@ -77,205 +75,12 @@ function git(args, cwd) {
 }
 
 /**
- * Is `dir` inside a git work tree? False when git is absent, when the path isn't
- * tracked, or on any error — the caller treats all three the same way.
+ * Does a repository hold `dir` — is it inside a work tree, in a folder that repository
+ * does not ignore (`repoOf`)? False when git is absent, outside any work tree, in an
+ * ignored folder, or on any error — the caller treats them all the same way.
  */
 export function isGitRepo(dir) {
-  try {
-    return git(['rev-parse', '--is-inside-work-tree'], dir).trim() === 'true'
-  } catch {
-    return false
-  }
-}
-
-/**
- * Uncommitted work under `relPaths`, relative to `dir`.
- *
- * Counts modified, staged, deleted AND untracked files. Untracked matters as much
- * as modified here: a section file that exists only locally is not on the backend,
- * so a pruning pull deletes it — losing work that was never committed anywhere.
- *
- * ⛔ **Returned relative to `dir`, which is NOT what git prints.** `--porcelain`
- * paths are always relative to the REPOSITORY ROOT, whatever directory it runs
- * in, so they only coincide with `dir`-relative when the site *is* the repo root.
- * Both callers do `join(siteDir, rel)` with the result, so the un-normalized form
- * was wrong for every nested layout — a site at `myproject/site/` inside a repo.
- *
- * What that cost, measured 2026-08-12: pull exempts its own previous output from
- * the uncommitted-work guard by looking each dirty path up in a record keyed
- * `dir`-relative (`utils/pull-written.js`). Given `myproject/site/site.yml` the
- * lookup missed, so **pull refused on files pull itself had written** — the exact
- * false alarm that record exists to prevent, and the one its own comment warns
- * teaches people to reach for `--force`. `captureLocalWork` had the same defect
- * one door along: it reads each path back with `join(siteDir, rel)`.
- *
- * The earlier `@returns` said "repo-relative-ish paths as git reports them" while
- * the summary above said "relative to `dir`" — the ambiguity was noticed and left,
- * and both callers had picked the other reading.
- *
- * @returns {string[]|null} paths relative to `dir`, or `null` when this isn't a
- *   git work tree (distinct from `[]`, which means "clean").
- */
-export function uncommittedUnder(dir, relPaths) {
-  if (!isGitRepo(dir)) return null
-  // ⚠️ Both sides must be REAL paths before `relative` can compare them.
-  // `rev-parse --show-toplevel` resolves symlinks; the caller's `dir` usually has
-  // not. On macOS that alone breaks it — `/var` is a symlink to `/private/var`,
-  // so a repo under the temp dir yields a root of `/private/var/…` against a dir
-  // of `/var/…`, and `relative` walks all the way up and back down. The result is
-  // a valid-looking path that matches nothing, i.e. the same silent miss this
-  // normalization exists to fix. Any symlinked checkout does it, not just tmp.
-  let root
-  let base
-  try {
-    root = git(['rev-parse', '--show-toplevel'], dir).trim()
-    base = realpathSync(dir)
-  } catch {
-    return null
-  }
-  try {
-    const out = git(
-      ['status', '--porcelain', '--untracked-files=all', '--', ...relPaths],
-      dir
-    )
-    return (
-      out
-        .split('\n')
-        .filter(Boolean)
-        // porcelain v1: XY<space>path, and a rename is "orig -> new".
-        .map((line) => line.slice(3).trim())
-        .map((p) => (p.includes(' -> ') ? p.split(' -> ')[1] : p))
-        // Porcelain paths are repo-root-relative; callers want them relative to
-        // `dir`. Quoted paths (git quotes names with spaces or non-ASCII when
-        // `core.quotePath` is on) are left alone rather than half-decoded — a
-        // wrong path is worse than an unmatched one here, since an unmatched
-        // path merely stays "dirty" and the guard errs toward refusing.
-        .map((p) => (p.startsWith('"') ? p : relative(base, join(root, p))))
-        .filter(Boolean)
-    )
-  } catch {
-    // A path git doesn't know (e.g. none of the roots exist yet) is not an error
-    // worth failing a pull over.
-    return []
-  }
-}
-
-/**
- * A file's content at HEAD — the ancestor of a three-way merge for a file no pull
- * wrote. For one a pull wrote, the ancestor is the version it wrote, found in history
- * by `findCommitted` below: HEAD stops being that version the moment an edit is
- * committed on top of it.
- *
- * Either way the ancestor is on this side, which is the point: the backend keeps no
- * per-version item content, and retaining some so it could feed a merge running on
- * the client would put a permanent second write on its hottest table. It doesn't
- * have to — the tool that already knows how to merge holds the history.
- *
- * ⛔ Until 2026-10-16 this called HEAD's content THE common ancestor ("`uniweb pull`
- * writes the backend's content into these files, so the committed version IS the
- * state both sides diverged from") — the rule `pull --merge` dropped on 2026-09-23.
- *
- * @returns {Buffer|null} null when the path isn't in HEAD — a file added locally and
- *   never committed has no ancestor; when the backend holds it too, `pull --merge`
- *   merges the two versions two-way.
- */
-export function showAtHead(dir, relPath) {
-  return showAt(dir, 'HEAD', relPath)
-}
-
-/**
- * A file's content at a revision, by a path relative to `dir`.
- *
- * ⛔ THE `./` IS WHAT MAKES THE PATH RELATIVE TO `dir`. In `<rev>:<path>` a bare path
- * is read from the REPOSITORY ROOT, whatever the cwd. With the repo at the project
- * root and the site in `site/` — the default layout — `HEAD:pages/home/hero.md`
- * named nothing, every lookup failed, and `pull --merge` "kept yours" for every file:
- * the backend's changes never merged in, while the pull recorded them as taken
- * (2026-09-23). Every merge test ran with the repo AT the site directory, the one
- * layout where a bare path happens to work.
- *
- * @returns {Buffer|null} null when the path isn't in that revision
- */
-export function showAt(dir, rev, relPath) {
-  try {
-    return execFileSync('git', ['show', `${rev}:./${relPath}`], {
-      cwd: dir,
-      stdio: ['ignore', 'pipe', 'ignore'],
-      maxBuffer: 64 * 1024 * 1024
-    })
-  } catch {
-    return null
-  }
-}
-
-/**
- * The most recent committed version of a file whose content hashes to `sha256` —
- * how the version a pull wrote is found again, as the ancestor of a merge.
- *
- * HEAD is that version only until the user commits an edit on top of it. After that
- * HEAD is THEIR edit, and a merge against it reads their change as the starting
- * point: the backend's version wins whole and the committed edit is reverted in the
- * working tree. The pull recorded the hash of what it wrote (`pull-written.json`),
- * so the version is recoverable from history by content, wherever it was committed.
- *
- * @param {number} [limit] - how many commits touching the file to search
- * @returns {Buffer|null} null when no committed version matches
- */
-export function findCommitted(dir, relPath, sha256, { limit = 50 } = {}) {
-  let revs
-  try {
-    revs = git(['log', `-n${limit}`, '--format=%H', '--', `./${relPath}`], dir)
-      .split('\n')
-      .filter(Boolean)
-  } catch {
-    return null
-  }
-  for (const rev of revs) {
-    const buf = showAt(dir, rev, relPath)
-    if (buf && createHash('sha256').update(buf).digest('hex') === sha256) return buf
-  }
-  return null
-}
-
-/**
- * Three-way merge, in place: `minePath` is rewritten with the merged result.
- *
- * Delegates to `git merge-file`, which is the same machinery git uses for a merge —
- * text that only one side touched is taken silently, and only genuine overlaps get
- * conflict markers. Building our own would be a worse version of a solved problem.
- *
- * @returns {{ merged: boolean, conflicted: boolean }} `merged:false` means the merge
- *   could not be attempted at all, which is different from attempting it and finding
- *   conflicts — the caller must not conflate them.
- */
-export function mergeFile(dir, minePath, basePath, theirsPath, labels = {}) {
-  try {
-    execFileSync(
-      'git',
-      [
-        'merge-file',
-        '-L',
-        labels.mine || 'yours (local)',
-        '-L',
-        labels.base || 'common ancestor',
-        '-L',
-        labels.theirs || 'theirs (backend)',
-        minePath,
-        basePath,
-        theirsPath
-      ],
-      { cwd: dir, stdio: ['ignore', 'ignore', 'ignore'] }
-    )
-    return { merged: true, conflicted: false }
-  } catch (err) {
-    // A positive status is the CONFLICT COUNT and the file still holds a valid
-    // merge with markers. Anything else (git missing, unreadable input) means no
-    // merge happened and the caller must fall back rather than trust the file.
-    if (typeof err?.status === 'number' && err.status > 0 && err.status < 128) {
-      return { merged: true, conflicted: true }
-    }
-    return { merged: false, conflicted: false }
-  }
+  return Boolean(repoOf(dir))
 }
 
 /** Does this repo have a remote configured to pull from? */
@@ -288,14 +93,19 @@ export function hasRemote(dir) {
 }
 
 /**
- * `git pull --ff-only` — bring in teammates' commits.
+ * `git pull`, merging — bring in teammates' commits.
  *
- * Fast-forward only, deliberately. A refresh should never silently create a merge
- * commit or drop the user into a rebase they didn't ask for; if the branches have
- * genuinely diverged, that is a git problem the user should handle in git, with
- * git's own vocabulary. We report and step back.
+ * ⭐ A MERGE, NOT A REBASE. A pull of the backend's content merges a sync point into the
+ * branch (`utils/sync-point.js`), and a rebase would replay that commit onto another
+ * base — no longer the backend's content, and no longer a base for the next merge. So the
+ * branch is merged with its remote too, whatever `pull.rebase` says, with uncommitted
+ * work stashed and put back (`--autostash`). A conflict is git's, settled with git's
+ * vocabulary; refresh reports it and steps back.
  *
- * @returns {{ ok: boolean, changed: boolean, message: string }}
+ * ⛔ Until 2026-10-17 this was `--ff-only`, which refused once a pull had made a merge
+ * commit the remote did not have.
+ *
+ * @returns {{ ok: boolean, conflicts?: boolean, changed: boolean, message: string }}
  */
 export function pullRemote(dir) {
   const before = (() => {
@@ -306,7 +116,7 @@ export function pullRemote(dir) {
     }
   })()
   try {
-    const out = execFileSync('git', ['pull', '--ff-only'], {
+    const out = execFileSync('git', ['pull', '--no-rebase', '--no-edit', '--autostash'], {
       cwd: dir,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe']
@@ -318,6 +128,23 @@ export function pullRemote(dir) {
         return null
       }
     })()
+    // ⛔ `--autostash` exits 0 when the uncommitted work it set aside cannot be put back over
+    // what the pull brought: the files hold conflict markers and git keeps that work in the
+    // stash as well. That is not a clean pull — refresh must stop before the backend's
+    // content lands on top of it. *(Read as clean until 2026-10-17.)*
+    const unmerged = git(['diff', '--name-only', '--diff-filter=U'], dir).trim()
+    if (unmerged) {
+      return {
+        ok: false,
+        conflicts: true,
+        changed: Boolean(before && after && before !== after),
+        message: [
+          'Your uncommitted changes overlap the commits git pull brought.',
+          'Settle the markers and `git add` each file, then `git stash drop` — git kept those changes in the stash as well:',
+          ...unmerged.split('\n').map((p) => `  ${p}`)
+        ].join('\n')
+      }
+    }
     return {
       ok: true,
       changed: Boolean(before && after && before !== after),