roadmodel 0.2.95__tar.gz → 0.2.97__tar.gz

{roadmodel-0.2.95 → roadmodel-0.2.97}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roadmodel
-Version: 0.2.95
+Version: 0.2.97
 Summary: BYO-key CLI that recommends the right AI model, platform, and settings for a prompt.
 Project-URL: Homepage, https://roadmodel.ai
 Project-URL: Repository, https://github.com/nathanramoscfa/roadmodel

{roadmodel-0.2.95/roadmodel/data → roadmodel-0.2.97/docs/claude-commands}/roadmap-refresh.md

@@ -221,7 +221,15 @@ complexity, novel or not; its Model rationale names them), then:
   not exist: a Complete step's ladder is the record of what ran, an `In
   progress` step's is what an agent is running, and a written phase's
   records what wrote its roadmap, so those keep their layout. That is a
-  layout fix, not a new pick, and takes no `Settings updated` line. A
+  layout fix, not a new pick, and takes no `Settings updated` line. Then
+  run `roadmodel rerank <every roadmap file>` (roadmodel 0.2.97 on): it
+  gives each of those ladder tables the ranks this release computes, so a
+  change to how roadmodel ranks reaches every step not yet run. It reads
+  the classification from the ladder's note (`Ranked for …`), else from the
+  only classification whose ladder has the same Picks. It adds a `Settings
+  updated` line where a rank changed. It reports any ladder it cannot
+  place: classify that step from its Model rationale and re-run with
+  `--hint FILE:SECTION=category/complexity[/novel]`. A
   ladder written before roadmodel 0.2.93 has Model / Backup / Platform /
   Effort (/ AA Index) / Thinking rows and no Runner-up: on a step that has
   not shipped, or a phase not yet written, replace it with the ladder

{roadmodel-0.2.95/roadmodel/data → roadmodel-0.2.97/docs/claude-commands}/roadmap-step.md

@@ -115,7 +115,11 @@ the dials and make sure it is set.
   Price rows. Level is the bare level of that platform's own dial (`High`
   is Intelligence High on Codex, Effort High on Claude Code and
   Antigravity). The ✓ in a column's header marks the one its **Runs:**
-  line names. A 0.2.94 ladder is three lists instead (`- Pick:`,
+  line names. From roadmodel 0.2.97 the three ranks of a column come from
+  three makers (a tight pool is a maker's); where too few are funded, a
+  missing rank is the Pick one level lower, its Level marked ↓, and the
+  note line says which classification the ladder was ranked for. A 0.2.94
+  ladder is three lists instead (`- Pick:`,
   `- Runner-up:`, `- Backup:` under each column's bold heading), and a
   0.2.93 one a table with rows `1 · Pick`, `2 · Runner-up` and
   `3 · Backup`, each followed by Platform, Effort, Thinking and AA Index
@@ -129,7 +133,8 @@ the dials and make sure it is set.
   subscription that pays for that column's Pick's platform:
   - `headroom`: run that column's Pick.
   - `tight`: run the first of that column's Runner-up and Backup whose
-    pool reads `headroom`, else the Cost column's Pick.
+    pool reads `headroom` or that is marked ↓ (the Pick one level lower,
+    which uses less of the tight pool), else the Cost column's Pick.
   - `exhausted`: run the first of that column's Runner-up and Backup
     whose pool reads `headroom`, else its Backup.
 

{roadmodel-0.2.95/roadmodel/data → roadmodel-0.2.97/docs/claude-commands}/roadmodel-upgrade.md

@@ -1,5 +1,5 @@
 ---
-description: Upgrade roadmodel and shared agent context across registered projects and configured machines (usage: /roadmodel-upgrade [project dirs to register…] [--sync-only | --check] [--local-only] [--skip-roadmap-refresh] [--refresh-roadmaps] [--install-schedule HH:MM])
+description: Upgrade roadmodel and shared agent context across registered projects and configured machines (usage: /roadmodel-upgrade [project dirs to register…] [--sync-only | --check] [--local-only] [--skip-roadmap-refresh] [--refresh-roadmaps] [--install-schedule HH:MM] [--install-sync-schedule [MINUTES]])
 ---
 Upgrade roadmodel in every registered project's own environment, refresh its
 `planning/` kit and agent commands, and maintain live shared rules, full
@@ -172,6 +172,24 @@ and registries are local; installing one schedule does not install another
 on a peer. When the operator has requested automatic upkeep, install and
 verify it within that authorization.
 
+**Checkout sync (roadmodel 0.2.96 on).** A roadmap change merged on GitHub
+reaches a project's checkout only when it pulls, so the editor kept showing
+the old version. `--install-sync-schedule [MINUTES]` (default 15) registers
+`--sync-checkouts` on its own schedule: launchd, Task Scheduler while the user
+is logged on, or cron. Every full run also syncs, after its roadmap refresh.
+For each registered checkout that sits on its default branch, it fetches
+origin and fast-forwards (`git merge --ff-only`). It never merges, rebases,
+stashes, resets or cleans. It leaves alone, and reports in the log, any
+checkout that:
+- is on a feature branch (an agent's step, which gets main when it rebases);
+- has local commits;
+- has a merge or rebase in progress;
+- has uncommitted changes to a file the update changes.
+
+Untracked files are never touched. `--uninstall-sync-schedule` removes it.
+The operator asked for this on 2026-10-25: install it on every machine, peers
+included (over SSH: `<python> <launcher> --install-sync-schedule`).
+
 ## 6. Refresh every project's roadmaps
 
 `--refresh-roadmaps` runs `/roadmap-refresh` in every registered project on

{roadmodel-0.2.95/roadmodel/data → roadmodel-0.2.97/docs/templates}/phase-roadmap-template.md

@@ -774,11 +774,18 @@ that owns it.}}
      platform has the toggle, and every AA Index and Price
      already assumes it. A note line under the table explains
      ✓ and Price, and a `**Conversation:**` line closes the
-     ladder. The ranks follow the column's own rule, not the
-     AA Index: Cost ranks the cheapest first, so its AA Index
-     may rise down the column. The Backup reads `none` when
-     the Runner-up already holds the
-     only other maker's models. Every model is the latest
+     ladder. Each rank comes from its own maker (roadmodel
+     0.2.97 on), because a tight usage pool is a maker's: the
+     Runner-up is the column's recommendation with the Pick's
+     maker left out, and the Backup leaves out both makers
+     above it. Where the user-context funds too few makers, a
+     missing rank is the Pick's own model one level lower,
+     its Level marked ↓ (it uses less of a tight pool), and
+     `none` below the dial's lowest level. The note line
+     names the classification the ladder was ranked for. The
+     ranks follow the column's own rule, not the AA Index:
+     Cost ranks each maker's cheapest adequate option, so its
+     AA Index may rise down the column. Every model is the latest
      version of its series, never an older one (GPT-6 Sol
      where GPT-6.1 Sol runs, Opus 5 where Opus 5.5 does).
      Set the Conversation line to **Continue** only when the

{roadmodel-0.2.95 → roadmodel-0.2.97}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "roadmodel"
-version = "0.2.95"
+version = "0.2.97"
 description = "BYO-key CLI that recommends the right AI model, platform, and settings for a prompt."
 readme = "README.md"
 requires-python = ">=3.11"

{roadmodel-0.2.95/docs/templates → roadmodel-0.2.97/roadmodel/data}/phase-roadmap-template.md

@@ -774,11 +774,18 @@ that owns it.}}
      platform has the toggle, and every AA Index and Price
      already assumes it. A note line under the table explains
      ✓ and Price, and a `**Conversation:**` line closes the
-     ladder. The ranks follow the column's own rule, not the
-     AA Index: Cost ranks the cheapest first, so its AA Index
-     may rise down the column. The Backup reads `none` when
-     the Runner-up already holds the
-     only other maker's models. Every model is the latest
+     ladder. Each rank comes from its own maker (roadmodel
+     0.2.97 on), because a tight usage pool is a maker's: the
+     Runner-up is the column's recommendation with the Pick's
+     maker left out, and the Backup leaves out both makers
+     above it. Where the user-context funds too few makers, a
+     missing rank is the Pick's own model one level lower,
+     its Level marked ↓ (it uses less of a tight pool), and
+     `none` below the dial's lowest level. The note line
+     names the classification the ladder was ranked for. The
+     ranks follow the column's own rule, not the AA Index:
+     Cost ranks each maker's cheapest adequate option, so its
+     AA Index may rise down the column. Every model is the latest
      version of its series, never an older one (GPT-6 Sol
      where GPT-6.1 Sol runs, Opus 5 where Opus 5.5 does).
      Set the Conversation line to **Continue** only when the

{roadmodel-0.2.95/docs/claude-commands → roadmodel-0.2.97/roadmodel/data}/roadmap-refresh.md

@@ -221,7 +221,15 @@ complexity, novel or not; its Model rationale names them), then:
   not exist: a Complete step's ladder is the record of what ran, an `In
   progress` step's is what an agent is running, and a written phase's
   records what wrote its roadmap, so those keep their layout. That is a
-  layout fix, not a new pick, and takes no `Settings updated` line. A
+  layout fix, not a new pick, and takes no `Settings updated` line. Then
+  run `roadmodel rerank <every roadmap file>` (roadmodel 0.2.97 on): it
+  gives each of those ladder tables the ranks this release computes, so a
+  change to how roadmodel ranks reaches every step not yet run. It reads
+  the classification from the ladder's note (`Ranked for …`), else from the
+  only classification whose ladder has the same Picks. It adds a `Settings
+  updated` line where a rank changed. It reports any ladder it cannot
+  place: classify that step from its Model rationale and re-run with
+  `--hint FILE:SECTION=category/complexity[/novel]`. A
   ladder written before roadmodel 0.2.93 has Model / Backup / Platform /
   Effort (/ AA Index) / Thinking rows and no Runner-up: on a step that has
   not shipped, or a phase not yet written, replace it with the ladder

{roadmodel-0.2.95/docs/claude-commands → roadmodel-0.2.97/roadmodel/data}/roadmap-step.md

@@ -115,7 +115,11 @@ the dials and make sure it is set.
   Price rows. Level is the bare level of that platform's own dial (`High`
   is Intelligence High on Codex, Effort High on Claude Code and
   Antigravity). The ✓ in a column's header marks the one its **Runs:**
-  line names. A 0.2.94 ladder is three lists instead (`- Pick:`,
+  line names. From roadmodel 0.2.97 the three ranks of a column come from
+  three makers (a tight pool is a maker's); where too few are funded, a
+  missing rank is the Pick one level lower, its Level marked ↓, and the
+  note line says which classification the ladder was ranked for. A 0.2.94
+  ladder is three lists instead (`- Pick:`,
   `- Runner-up:`, `- Backup:` under each column's bold heading), and a
   0.2.93 one a table with rows `1 · Pick`, `2 · Runner-up` and
   `3 · Backup`, each followed by Platform, Effort, Thinking and AA Index
@@ -129,7 +133,8 @@ the dials and make sure it is set.
   subscription that pays for that column's Pick's platform:
   - `headroom`: run that column's Pick.
   - `tight`: run the first of that column's Runner-up and Backup whose
-    pool reads `headroom`, else the Cost column's Pick.
+    pool reads `headroom` or that is marked ↓ (the Pick one level lower,
+    which uses less of the tight pool), else the Cost column's Pick.
   - `exhausted`: run the first of that column's Runner-up and Backup
     whose pool reads `headroom`, else its Backup.
 

{roadmodel-0.2.95/docs/claude-commands → roadmodel-0.2.97/roadmodel/data}/roadmodel-upgrade.md

@@ -1,5 +1,5 @@
 ---
-description: Upgrade roadmodel and shared agent context across registered projects and configured machines (usage: /roadmodel-upgrade [project dirs to register…] [--sync-only | --check] [--local-only] [--skip-roadmap-refresh] [--refresh-roadmaps] [--install-schedule HH:MM])
+description: Upgrade roadmodel and shared agent context across registered projects and configured machines (usage: /roadmodel-upgrade [project dirs to register…] [--sync-only | --check] [--local-only] [--skip-roadmap-refresh] [--refresh-roadmaps] [--install-schedule HH:MM] [--install-sync-schedule [MINUTES]])
 ---
 Upgrade roadmodel in every registered project's own environment, refresh its
 `planning/` kit and agent commands, and maintain live shared rules, full
@@ -172,6 +172,24 @@ and registries are local; installing one schedule does not install another
 on a peer. When the operator has requested automatic upkeep, install and
 verify it within that authorization.
 
+**Checkout sync (roadmodel 0.2.96 on).** A roadmap change merged on GitHub
+reaches a project's checkout only when it pulls, so the editor kept showing
+the old version. `--install-sync-schedule [MINUTES]` (default 15) registers
+`--sync-checkouts` on its own schedule: launchd, Task Scheduler while the user
+is logged on, or cron. Every full run also syncs, after its roadmap refresh.
+For each registered checkout that sits on its default branch, it fetches
+origin and fast-forwards (`git merge --ff-only`). It never merges, rebases,
+stashes, resets or cleans. It leaves alone, and reports in the log, any
+checkout that:
+- is on a feature branch (an agent's step, which gets main when it rebases);
+- has local commits;
+- has a merge or rebase in progress;
+- has uncommitted changes to a file the update changes.
+
+Untracked files are never touched. `--uninstall-sync-schedule` removes it.
+The operator asked for this on 2026-10-25: install it on every machine, peers
+included (over SSH: `<python> <launcher> --install-sync-schedule`).
+
 ## 6. Refresh every project's roadmaps
 
 `--refresh-roadmaps` runs `/roadmap-refresh` in every registered project on

{roadmodel-0.2.95 → roadmodel-0.2.97}/scripts/update_projects.py

@@ -2019,6 +2019,11 @@ def refresh_roadmaps(
 SCHEDULE_LABEL = "com.roadmodel.update-projects"  # launchd label / cron marker
 TASK_NAME = "roadmodel-update-projects"  # Windows Task Scheduler name
 LOG_FILE = CONFIG_DIR / "update.log"
+# The checkout sync's own schedule: fast-forward every registered checkout on
+# its default branch every SYNC_MINUTES (sync_checkout, below).
+SYNC_LABEL = "com.roadmodel.sync-checkouts"
+SYNC_TASK = "roadmodel-sync-checkouts"
+SYNC_MINUTES = 15
 LOG_MAX_BYTES = 1_000_000
 
 
@@ -2258,6 +2263,243 @@ def uninstall_schedule(dry_run: bool = False) -> str:
     return "removed crontab entry"
 
 
+def _sync_argv(python: Path, script: Path) -> list[str]:
+    return [str(python), "-I", "-X", "utf8", str(script), "--sync-checkouts", "--log"]
+
+
+def sync_launchd_plist(python: Path, script: Path, minutes: int) -> str:
+    """The checkout sync as a launchd agent that starts every ``minutes``."""
+    args = "".join(
+        f"    <string>{escape(a)}</string>\n" for a in _sync_argv(python, script)
+    )
+    return f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>{SYNC_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+{args}  </array>
+  <key>StartInterval</key><integer>{minutes * 60}</integer>
+  <key>RunAtLoad</key><true/>
+  <key>StandardOutPath</key><string>/dev/null</string>
+  <key>StandardErrorPath</key><string>/dev/null</string>
+  <key>EnvironmentVariables</key>
+  <dict><key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string></dict>
+</dict>
+</plist>
+"""
+
+
+def sync_schtasks_argv(python: Path, script: Path, minutes: int) -> list[str]:
+    """The checkout sync as a Task Scheduler task that repeats every
+    ``minutes`` while the user is logged on (git reads their credentials)."""
+    return [
+        "schtasks", "/Create", "/F",
+        "/TN", SYNC_TASK,
+        "/SC", "MINUTE",
+        "/MO", str(minutes),
+        "/TR", subprocess.list2cmdline(_sync_argv(python, script)),
+    ]  # fmt: skip
+
+
+def sync_cron_line(python: Path, script: Path, minutes: int) -> str:
+    command = shlex.join(_sync_argv(python, script)).replace("%", r"\%")
+    return f"*/{minutes} * * * * {command}  # {SYNC_LABEL}"
+
+
+def install_sync_schedule(minutes: int, dry_run: bool = False) -> str:
+    """Register the checkout sync to run every ``minutes`` for this user."""
+    if not 1 <= minutes <= 1440:
+        raise SystemExit("--install-sync-schedule: minutes must be 1–1440")
+    python = _launcher_python()
+    script = _install_launcher(dry_run)
+    stamp = f"every {minutes} min via {python} {script} --sync-checkouts (log: {LOG_FILE})"
+    if sys.platform == "darwin":
+        plist = Path.home() / "Library" / "LaunchAgents" / f"{SYNC_LABEL}.plist"
+        if dry_run:
+            return f"launchd agent {plist} — {stamp}"
+        plist.parent.mkdir(parents=True, exist_ok=True)
+        domain = f"gui/{os.getuid()}"
+        _sys(["launchctl", "bootout", f"{domain}/{SYNC_LABEL}"])  # ok if not loaded
+        _replace_bytes(plist, sync_launchd_plist(python, script, minutes).encode("utf-8"))
+        cp = _sys(["launchctl", "bootstrap", domain, str(plist)])
+        if cp.returncode != 0:
+            raise SystemExit(f"launchctl bootstrap failed: {cp.stderr.strip() or cp.stdout.strip()}")
+        return f"launchd agent {plist} — {stamp}"
+    if WINDOWS:
+        if dry_run:
+            return f"Task Scheduler task {SYNC_TASK} — {stamp}"
+        cp = _sys(sync_schtasks_argv(python, script, minutes))
+        if cp.returncode != 0:
+            raise SystemExit(f"schtasks failed: {cp.stderr.strip() or cp.stdout.strip()}")
+        return f"Task Scheduler task {SYNC_TASK} — {stamp}"
+    line = sync_cron_line(python, script, minutes)
+    if dry_run:
+        return f"crontab entry — {stamp}\n  {line}"
+    current = _sys(["crontab", "-l"])
+    kept = [
+        ln
+        for ln in (current.stdout if current.returncode == 0 else "").splitlines()
+        if SYNC_LABEL not in ln
+    ]
+    cp = _sys(["crontab", "-"], stdin="\n".join(kept + [line]) + "\n")
+    if cp.returncode != 0:
+        raise SystemExit(f"crontab failed: {cp.stderr.strip()}")
+    return f"crontab entry — {stamp}"
+
+
+def uninstall_sync_schedule(dry_run: bool = False) -> str:
+    if sys.platform == "darwin":
+        plist = Path.home() / "Library" / "LaunchAgents" / f"{SYNC_LABEL}.plist"
+        if not dry_run:
+            _sys(["launchctl", "bootout", f"gui/{os.getuid()}/{SYNC_LABEL}"])
+            plist.unlink(missing_ok=True)
+        return f"removed launchd agent {plist}"
+    if WINDOWS:
+        if not dry_run:
+            _sys(["schtasks", "/Delete", "/F", "/TN", SYNC_TASK])
+        return f"removed Task Scheduler task {SYNC_TASK}"
+    if not dry_run:
+        current = _sys(["crontab", "-l"])
+        kept = [
+            ln
+            for ln in (current.stdout if current.returncode == 0 else "").splitlines()
+            if SYNC_LABEL not in ln
+        ]
+        _sys(["crontab", "-"], stdin="\n".join(kept) + "\n")
+    return "removed crontab entry"
+
+
+# --------------------------------------------------------------------------
+# Checkout sync
+# --------------------------------------------------------------------------
+# The operator reads roadmaps in each project's own checkout. A roadmap change
+# merged on GitHub (a fleet `roadmodel relayout`, a refresh, a step run on the
+# other machine) reached that checkout only after a manual `git pull`, so the
+# editor kept showing the old version (2026-10-25). --sync-checkouts runs on
+# its own schedule (every SYNC_MINUTES) and at the end of every full run, and
+# only ever fast-forwards where nothing can be lost:
+# - the checkout must sit on its default branch; a feature branch, an agent's
+#   step, is left alone and gets main when it rebases;
+# - `git merge --ff-only` only: never a merge commit, rebase, stash, reset or
+#   clean, and untracked files are never touched;
+# - local commits, a merge/rebase/cherry-pick in progress, or uncommitted
+#   changes to a file the update changes leave the checkout as it is.
+
+SYNC_GIT_TIMEOUT = 120
+_SYNC_BUSY = ("MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD", "rebase-merge", "rebase-apply")
+
+
+@dataclass(frozen=True)
+class SyncOutcome:
+    """What one checkout's sync did: `updated`, `current`, `skipped` (left
+    alone on purpose) or `failed` (git could not do what was asked)."""
+
+    path: Path
+    state: str
+    detail: str
+
+    def line(self) -> str:
+        return f"{self.path.name}: {self.state} — {self.detail}"
+
+
+def _checkout_git(repo: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(  # noqa: S603 — fixed git argv, paths from the registry
+        ["git", "-C", str(repo), *args],  # noqa: S607 — git resolved on PATH, as elsewhere
+        capture_output=True,
+        text=True,
+        timeout=SYNC_GIT_TIMEOUT,
+    )
+
+
+def _first_line(cp: subprocess.CompletedProcess[str]) -> str:
+    text = (cp.stderr or cp.stdout or "").strip()
+    return text.splitlines()[0] if text else f"exit {cp.returncode}"
+
+
+def default_branch(repo: Path) -> Optional[str]:
+    """The remote's default branch as this clone knows it (`origin/HEAD`),
+    else whichever of main and master origin has; None when neither."""
+    cp = _checkout_git(repo, "symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD")
+    name = cp.stdout.strip()
+    if cp.returncode == 0 and name.startswith("origin/"):
+        return name[len("origin/") :]
+    for branch in ("main", "master"):
+        ref = f"refs/remotes/origin/{branch}"
+        if _checkout_git(repo, "rev-parse", "--verify", "--quiet", ref).returncode == 0:
+            return branch
+    return None
+
+
+def _checkout_busy(repo: Path) -> bool:
+    cp = _checkout_git(repo, "rev-parse", "--git-dir")
+    if cp.returncode != 0:
+        return False
+    git_dir = Path(cp.stdout.strip())
+    if not git_dir.is_absolute():
+        git_dir = repo / git_dir
+    markers = (*_SYNC_BUSY, "index.lock")
+    return any((git_dir / marker).exists() for marker in markers)
+
+
+def sync_checkout(repo: Path, *, dry_run: bool = False) -> SyncOutcome:
+    """Fast-forward ``repo`` to ``origin/<default branch>`` when it is on that
+    branch and nothing of its own would be lost; otherwise leave it and say
+    why."""
+    repo = Path(repo)
+    if not (repo / ".git").exists():
+        return SyncOutcome(repo, "skipped", "not a git checkout")
+    head = _checkout_git(repo, "symbolic-ref", "--quiet", "--short", "HEAD")
+    if head.returncode != 0:
+        return SyncOutcome(repo, "skipped", "detached HEAD")
+    branch = head.stdout.strip()
+    if _checkout_busy(repo):
+        return SyncOutcome(repo, "skipped", "a merge, rebase or cherry-pick is in progress")
+    default = default_branch(repo)
+    if default is None:
+        return SyncOutcome(repo, "skipped", "origin has no main or master")
+    if branch != default:
+        return SyncOutcome(repo, "skipped", f"on {branch}; it gets {default} when it rebases")
+    fetched = _checkout_git(repo, "fetch", "--quiet", "origin", default)
+    if fetched.returncode != 0:
+        return SyncOutcome(repo, "failed", f"fetch failed: {_first_line(fetched)}")
+    counts = _checkout_git(repo, "rev-list", "--left-right", "--count", f"HEAD...origin/{default}")
+    if counts.returncode != 0:
+        return SyncOutcome(repo, "failed", f"cannot compare with origin: {_first_line(counts)}")
+    ahead, behind = (int(n) for n in counts.stdout.split())
+    if behind == 0:
+        return SyncOutcome(repo, "current", f"{default} is up to date")
+    if ahead:
+        return SyncOutcome(
+            repo, "skipped", f"{ahead} local commit(s) on {default} not on origin; not touched"
+        )
+    if dry_run:
+        return SyncOutcome(repo, "updated", f"would fast-forward {behind} commit(s)")
+    merged = _checkout_git(repo, "merge", "--ff-only", "--quiet", f"origin/{default}")
+    if merged.returncode != 0:
+        return SyncOutcome(
+            repo,
+            "skipped",
+            f"{behind} commit(s) behind, but local changes block a fast-forward: "
+            f"{_first_line(merged)}",
+        )
+    sha = _checkout_git(repo, "rev-parse", "--short", "HEAD").stdout.strip()
+    return SyncOutcome(repo, "updated", f"fast-forwarded {behind} commit(s) to {sha}")
+
+
+def sync_checkouts(paths: list[Path], dry_run: bool = False) -> list[str]:
+    """:func:`sync_checkout` for each checkout, one line each; a git that
+    hangs or is missing fails that checkout only."""
+    lines = []
+    for repo in paths:
+        try:
+            lines.append(sync_checkout(repo, dry_run=dry_run).line())
+        except (OSError, subprocess.SubprocessError) as exc:
+            lines.append(SyncOutcome(Path(repo), "failed", f"git did not run: {exc}").line())
+    return lines
+
+
 class _Tee:
     """Write to the console and append to the log (scheduled runs)."""
 
@@ -2840,6 +3082,25 @@ def _parser() -> argparse.ArgumentParser:
         help="also register a daily unattended run at HH:MM (default 09:00) for this user",
     )
     ap.add_argument("--uninstall-schedule", action="store_true", help="remove the daily run")
+    ap.add_argument(
+        "--sync-checkouts",
+        action="store_true",
+        help=(
+            "fast-forward each registered checkout that sits on its default branch to "
+            "origin, when nothing local would be lost; no package upgrades"
+        ),
+    )
+    ap.add_argument(
+        "--install-sync-schedule",
+        nargs="?",
+        type=int,
+        const=SYNC_MINUTES,
+        metavar="MINUTES",
+        help=f"also register --sync-checkouts every MINUTES (default {SYNC_MINUTES})",
+    )
+    ap.add_argument(
+        "--uninstall-sync-schedule", action="store_true", help="remove the checkout sync"
+    )
     ap.add_argument("--log", action="store_true", help=f"also append output to {LOG_FILE}")
     ap.add_argument(
         "--no-parity",
@@ -2935,7 +3196,13 @@ def _main(argv: Optional[list[str]] = None) -> int:
         log_fh = _open_log()
         sys.stdout = _Tee(sys.__stdout__, log_fh)
         sys.stderr = _Tee(sys.__stderr__, log_fh)
-    if should_self_update() and not {"-h", "--help", "--check", "--sync-only"} & set(raw):
+    if should_self_update() and not {
+        "-h",
+        "--help",
+        "--check",
+        "--sync-only",
+        "--sync-checkouts",
+    } & set(raw):
         if pre.dry_run:
             print("self-update: skipped (dry run); this is the local copy's plan")
         else:
@@ -2970,6 +3237,23 @@ def _main(argv: Optional[list[str]] = None) -> int:
 
     if args.context_source and not args.context_sync:
         raise SystemExit("--context-source needs --context-sync OWNER/REPO")
+    if args.sync_checkouts:
+        # Its own frequent schedule: only git fast-forwards, no upgrades.
+        paths = [Path(p) for p in args.projects] or [
+            e.path for e in read_registry(args.projects_file)
+        ]
+        print("Checkouts:")
+        for line in sync_checkouts(paths, dry_run=args.dry_run):
+            print(f"  {line}")
+        return 0
+    if args.uninstall_sync_schedule:
+        print("Checkout sync:", uninstall_sync_schedule(dry_run=args.dry_run))
+        if not args.projects and not args.add and args.install_sync_schedule is None:
+            return 0
+    if args.install_sync_schedule is not None:
+        print("Checkout sync:", install_sync_schedule(args.install_sync_schedule, args.dry_run))
+        if not args.projects and not args.add:
+            return 0
     # A pre-companion launcher (for example 0.2.65) refreshed only this module
     # before handing over. Repair the complete installed release on this first
     # full run, so the next offline --sync-only does not need another upgrade.
@@ -3113,6 +3397,12 @@ def _main(argv: Optional[list[str]] = None) -> int:
         for line in lines:
             print(f"  {line}")
 
+    # After the refresh, which may have merged roadmap PRs: bring each checkout
+    # on its default branch up to origin so the editor shows them.
+    print("\nCheckouts:")
+    for line in sync_checkouts([e.path for e in entries], dry_run=args.dry_run):
+        print(f"  {line}")
+
     peers_ok = upgrade_peers(args)
     failed = [r for r in results if not r.ok]
     if failed:

{roadmodel-0.2.95 → roadmodel-0.2.97}/src/roadmodel/__init__.py

@@ -1,2 +1,2 @@
 # src/roadmodel/__init__.py
-__version__ = "0.2.95"
+__version__ = "0.2.97"