refactor(lpb-devstack): one repo map, status/sync/sync-pins, no compat layers

- repos: single 6-repo map (WORKSPACE_REPOS + CONFIG_REPO); TAG_REPOS and
  LPB_EXTENSION_REPOS now derived; repo_path()/stack_repos() helpers
- workspace: drop 'ensure' (broken subset of sync: no clone/symlink/ff,
  config path lacked branch tracking); 'sync --extensions' becomes the
  'sync-pins' subcommand; config handling unified via _status_config/
  _sync_config
- workspace sync: discard dependency-lockfile drift (package-manager
  rewrites, e.g. npm 12 dropping hasShrinkwrap) before the dirty check so
  extension clones can't be blocked by npm rewrites
- version: expected_branch() covers config; new expected_pin_version()
  shared by validate + sync-pins; _devstack_root_candidates() unifies the
  triple repo-root discovery loops
- _ensure_branch_tracked: capture fetched commit before follow-up fetches
  (fixes FETCH_HEAD overwrite on restricted-refspec clones); fewer fetches
- delete localpibox._stack_lib compat shim; all callers import from
  localpibox.stack.* directly
- CLIs: single canonical copy in scripts/ (support/ entries were symlinks
  to real files there; removed); Dockerfile + install.sh point at scripts/
- tests: patch targets move to owning modules; new lockfile-drift and
  expected_pin_version tests
- docs: lpb-devstack.md, config-repo.md, lpb-config.md,
  manual-tagging-and-config-split.md

Author: lpb-docs

Dockerfile

@@ -174,9 +174,13 @@ COPY support/validate-subagent-output.ts /opt/pi-support/validate-subagent-outpu
 COPY support/config/ /opt/pi-support/config/
 COPY support/docs/ /opt/pi-support/docs/
 COPY support/schemas/ /opt/pi-support/schemas/
-# Shared Python helpers used by the ported support tools (import via the
-# script directory, which Python adds to sys.path automatically).
+# ── Shared Python helpers + user-facing CLIs ─────────────────────────────
+# The localpibox package and the lpb-config/lpb-devstack CLIs are the source of
+# truth in scripts/ (single copy — no support/ duplicates). They must live
+# under /opt/pi-support/ for their sys.path resolution.
 COPY scripts/localpibox/ /opt/pi-support/localpibox/
+COPY --chmod=755 scripts/lpb-config /opt/pi-support/lpb-config
+COPY --chmod=755 scripts/lpb-devstack /opt/pi-support/lpb-devstack
 
 # ── Devstack deployment scripts ──
 COPY --chmod=755 support/install-browser.py /opt/devstack/install-browser.py
@@ -204,8 +208,6 @@ RUN mkdir -p /home/lpb/.local/bin \
 # lpb-config / lpb-devstack need to live under /opt/pi-support/ for their
 # sys.path resolution (the localpibox package is copied there above).
 # Symlinks at ~/.local/bin give users the clean CLI names.
-COPY --chmod=755 support/lpb-config /opt/pi-support/lpb-config
-COPY --chmod=755 support/lpb-devstack /opt/pi-support/lpb-devstack
 
 # ── Root operations: ownership + gitconfig + shell PATH ─────────────────────
 USER root

doc/config-repo.md

@@ -71,7 +71,7 @@ Extensions are pinned in the `packages` array of `settings.json` as
 
 The `__LPB_VERSION__` placeholder in the template is replaced with the
 stack version at boot. Pins are synced to a new stack version by
-`lpb-devstack workspace sync --extensions`.
+`lpb-devstack workspace sync-pins`.
 
 ## Extension Clones
 
@@ -142,7 +142,7 @@ lpb-config update
 lpb-devstack validate
 
 # Sync extension pins to stack version
-lpb-devstack workspace sync --extensions
+lpb-devstack workspace sync-pins
 
 # Reset config repo
 lpb-config reset

doc/lpb-config.md

@@ -47,7 +47,7 @@ Settings.json is **template-driven**, not git-tracked:
 1. Config repo ships `settings.json.template` with `__LPB_VERSION__` placeholders
 2. First boot: `start.sh` generates `settings.json` (replaces placeholders)
 3. No model/provider preconfigured — user runs `/login lemonade`
-4. Pin sync: `lpb-devstack workspace sync --extensions` (main pipeline reads
+4. Pin sync: `lpb-devstack workspace sync-pins` (main pipeline reads
    stable version from devstack `origin/main`)
 5. `lpb-devstack validate` checks pins match the current stack version
 6. Settings.json persists on the host volume — survives container rebuilds

doc/lpb-devstack.md

@@ -50,9 +50,8 @@ partially-tagged stack is a release bug.
 | Command | Description |
 |---|---|
 | `lpb-devstack workspace status` | Show branches + alignment for all repos |
-| `lpb-devstack workspace sync` | Clone missing repos, create symlinks, align branches, pull latest |
-| `lpb-devstack workspace sync --extensions` | Sync settings.json pins to stack version |
-| `lpb-devstack workspace ensure [--fix]` | Check/fix branch alignment for the pipeline |
+| `lpb-devstack workspace sync` | Clone missing repos, create symlinks, align branches, pull latest (the single write path) |
+| `lpb-devstack workspace sync-pins` | Sync settings.json pins to the pipeline's stack version |
 
 ### Stack Validation
 
@@ -116,7 +115,7 @@ lpb-devstack release status                    # readiness check
 lpb-devstack release promote --dry-run         # inspect plan
 lpb-devstack release promote                   # dev → stable + push
 lpb-devstack tag-repos --branch main           # tag the 5 repos on stable branches
-lpb-devstack --tag main workspace sync --extensions   # pins → stable tag
+lpb-devstack --tag main workspace sync-pins   # pins → stable tag
 pi update --extensions
 ```
 

doc/manual-tagging-and-config-split.md

@@ -105,9 +105,8 @@ lpb-devstack tag-repos --version v   # explicit version
 
 # Workspace management
 lpb-devstack workspace status        — branches + alignment
-lpb-devstack workspace sync          — clone/symlink/align/pull
-lpb-devstack workspace sync --extensions — sync settings.json pins
-lpb-devstack workspace ensure [--fix] — switch to correct branches
+lpb-devstack workspace sync          — clone/symlink/align/pull (single write path)
+lpb-devstack workspace sync-pins     — sync settings.json pins
 
 # Stack validation
 lpb-devstack validate                — full stack alignment check
@@ -129,7 +128,7 @@ lpb-devstack validate-hooks          — run full pre-commit checks (tests + val
 | Memory config | ✅ | ❌ | Image-usable, needed inside container |
 | VERSION bumping | ❌ | ✅ | Devstack-specific, workspace tool |
 | Tag repos | ❌ | ✅ | Dev-time operation |
-| Workspace sync/ensure | ❌ | ✅ | Developer workspace maintenance |
+| Workspace sync/status | ❌ | ✅ | Developer workspace maintenance |
 | Stack validation | ❌ | ✅ | Dev-time operation |
 | Release promote | ❌ | ✅ | Dev→stable promotion |
 | Pre-commit validation | ❌ | ✅ | Dev-time operation |
@@ -138,18 +137,17 @@ lpb-devstack validate-hooks          — run full pre-commit checks (tests + val
 
 ```
 devstack/
-├── support/
-│   ├── lpb-config          ← slimmed down (config repo only, ~250 lines)
-│   └── lpb-devstack        ← new (devops, ~600 lines)
-├── scripts/
-│   ├── lpb-config          ← symlink → ../support/lpb-config
-│   ├── lpb-devstack        ← symlink → ../support/lpb-devstack
+├── support/                  ← runtime image tools (start.sh, browser*, validate.py, …)
+├── scripts/                  ← single source for the CLIs + shared package
+│   ├── lpb-config            ← config repo manager
+│   ├── lpb-devstack          ← DevOps workspace tool
 │   ├── localpibox/
-│   │   ├── _stack_lib.py   ← shared code (git, repo defs, pipeline detection)
+│   │   ├── stack/            ← gitutil / repos / version / workspace / validate / release
 │   │   └── ...
-│   └── install.sh          ← install both scripts
+│   ├── install.sh            ← installs both CLIs + localpibox (from scripts/)
+│   └── test_*                ← test suite
 └── .githooks/
-    └── pre-commit          ← keep full check (tests included)
+    └── pre-commit            ← keep full check (tests included)
 ```
 
 ---
@@ -219,7 +217,12 @@ intent):
 
 8. Follow-up reorg (same day): `_stack_lib.py` was split into the
    `localpibox/stack/` package (`gitutil` / `repos` / `version` /
-   `workspace` / `validate` / `release`); `_stack_lib.py` remains a thin
-   compat shim so existing imports are unchanged. `test_env_bridge.sh`
+   `workspace` / `validate` / `release`); `_stack_lib.py` remained a thin
+   compat shim so existing imports were unchanged. `test_env_bridge.sh`
    (previously orphaned) is wired into CI and now isolates its subshells
    from the ambient environment.
+
+   (2026-08-21 cleanup: the compat shim was deleted — all callers import
+   from `localpibox.stack.*` directly; the CLI canonical copies moved from
+   `support/` to `scripts/` with the symlinks removed, and the Dockerfile /
+   `install.sh` point at `scripts/`.)

scripts/install.sh

@@ -45,11 +45,11 @@ curl -fsSL "https://raw.githubusercontent.com/${OWNER_REPO}/main/VERSION" -o "${
 #     localpibox package they import (resolved via ~/.lpb-stack/devstack/).
 echo "Installing lpb-config + lpb-devstack..."
 for tool in lpb-config lpb-devstack; do
-    curl -fsSL "https://raw.githubusercontent.com/${OWNER_REPO}/main/support/${tool}" -o "${INSTALL_DIR}/${tool}"
+    curl -fsSL "https://raw.githubusercontent.com/${OWNER_REPO}/main/scripts/${tool}" -o "${INSTALL_DIR}/${tool}"
     chmod +x "${INSTALL_DIR}/${tool}"
 done
 mkdir -p "${CONFIG_DIR}/localpibox/stack"
-for f in __init__.py cli.py env.py log.py run.py _stack_lib.py; do
+for f in __init__.py cli.py env.py log.py run.py; do
     curl -fsSL "https://raw.githubusercontent.com/${OWNER_REPO}/main/scripts/localpibox/${f}" -o "${CONFIG_DIR}/localpibox/${f}"
 done
 for f in __init__.py gitutil.py repos.py version.py workspace.py validate.py release.py; do

scripts/localpibox/__init__.py

@@ -7,9 +7,8 @@
   log      — colored console output (info/warn/error/done/debug)
   run      — subprocess helpers, tool discovery, container detection
   cli      — argument-parser helpers, prompts, fatal-error exit
-  stack/   — LocalPibox stack operations (git helpers, repo map, pipeline
-             detection, VERSION bump math, workspace/validate/release)
-             (legacy import path: localpibox._stack_lib shim)
+  stack/   — LocalPibox stack operations (git helpers, single 6-repo map,
+             pipeline detection, VERSION bump math, workspace/validate/release)
 """
 
 from .env import (

scripts/localpibox/_stack_lib.py

@@ -1,25 +1,26 @@
 """localpibox.stack — LocalPibox stack operations library.
 
-Module layout (split from the former single _stack_lib module):
+Module layout:
 
   gitutil   — git helpers (plain + GitHub-auth aware)
-  repos     — path constants, 6-repo stack map, tagging repo list
-  version   — pipeline detection, VERSION discovery + bump math, stack env
-  workspace — workspace sync/clone/ensure + settings.json pin helpers
+  repos     — path constants, single 6-repo stack map (workspace repos +
+              config repo) and everything derived from it
+  version   — pipeline detection, VERSION discovery + bump math, stack env,
+              expected branches/pins
+  workspace — workspace sync/clone + settings.json pin helpers
   validate  — full-stack alignment validation
   release   — stable-release promotion engine (dev → stable)
 
-Import the public API from this package, or from the legacy
-``localpibox._stack_lib`` shim (kept for backwards compatibility).
+Import the public API from this package or from the owning module.
 """
 
 from .gitutil import git, git_auth, git_remote
 from .repos import (
     AGENT_GIT,
+    CONFIG_REPO,
     DEFAULT_AGENT_DIR,
     DEFAULT_REMOTE,
     DEFAULT_REF,
-    EXTENSION_REPOS,
     LPB_EXTENSION_REPOS,
     MIGRATE_KEEP,
     MEMORY_CONFIG_PATH,
@@ -29,30 +30,32 @@
     WORKSPACE_REPOS,
     WORKSPACE_ROOT,
     migrate_legacy_layout,
+    repo_path,
+    stack_repos,
 )
 from .version import (
     bump_version,
     detect_pipeline,
     expected_branch,
+    expected_pin_version,
     get_stack_env,
     get_version,
     parse_version,
 )
 from .workspace import (
-    cmd_workspace_ensure,
     cmd_workspace_status,
     cmd_workspace_sync,
-    cmd_workspace_sync_extensions,
+    cmd_workspace_sync_pins,
 )
 from .validate import cmd_validate
 from .release import cmd_release_promote, cmd_release_status
 
 __all__ = [
     "AGENT_GIT",
+    "CONFIG_REPO",
     "DEFAULT_AGENT_DIR",
     "DEFAULT_REMOTE",
     "DEFAULT_REF",
-    "EXTENSION_REPOS",
     "LPB_EXTENSION_REPOS",
     "MIGRATE_KEEP",
     "MEMORY_CONFIG_PATH",
@@ -65,17 +68,19 @@
     "cmd_release_promote",
     "cmd_release_status",
     "cmd_validate",
-    "cmd_workspace_ensure",
     "cmd_workspace_status",
     "cmd_workspace_sync",
-    "cmd_workspace_sync_extensions",
+    "cmd_workspace_sync_pins",
     "detect_pipeline",
     "expected_branch",
+    "expected_pin_version",
     "get_stack_env",
     "get_version",
     "git",
     "git_auth",
     "git_remote",
     "migrate_legacy_layout",
     "parse_version",
+    "repo_path",
+    "stack_repos",
 ]

scripts/localpibox/stack/__init__.py

@@ -15,19 +15,16 @@
 from ..cli import confirm
 from ..log import Console
 from .gitutil import git, git_auth
-from .repos import DEFAULT_AGENT_DIR, WORKSPACE_REPOS, WORKSPACE_ROOT
+from .repos import repo_path, stack_repos
 from .version import get_version
 
 
 def _release_repos() -> list[tuple[str, Path, str, str, str]]:
     """All 6 stack repos: (label, path, dev_branch, main_branch, github_repo)."""
-    repos: list[tuple[str, Path, str, str, str]] = []
-    for name, _is_sym, _is_ext, dev_branch, main_branch in WORKSPACE_REPOS:
-        repos.append((name, WORKSPACE_ROOT / name, dev_branch, main_branch,
-                      f"lpb-stack/{name}"))
-    repos.append(("config", Path(DEFAULT_AGENT_DIR), "dev", "main",
-                  "lpb-stack/config"))
-    return repos
+    return [
+        (name, repo_path(name), dev_branch, main_branch, f"lpb-stack/{name}")
+        for name, dev_branch, main_branch in stack_repos()
+    ]
 
 
 def _repo_release_state(path: Path, dev_branch: str, main_branch: str,
@@ -355,7 +352,7 @@ def cmd_release_promote(*, assume_yes: bool, dry_run: bool, rebase: bool,
     cons.info(f"CI (main pipeline) now builds :{stable_version}-* / :main-* / :latest-*")
     cons.info("and tags the 5 repos at the stable branches.")
     cons.info("After CI passes:")
-    cons.info("  1. lpb-devstack --tag main workspace sync --extensions")
+    cons.info("  1. lpb-devstack --tag main workspace sync-pins")
     cons.info("  2. pi update --extensions")
     cons.info(f"  (If CI's tag-repos didn't run: lpb-devstack tag-repos --branch main --version {stable_version})")
     return 0