@zerwiz/ymir 0.1.4 → 0.1.7

package/bin/omarchy-plugins.sh

@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+# omarchy-plugins.sh — the Omarchy plugins Ymir suggests, and installs on consent.
+#
+# Ymir runs on Omarchy, and Omarchy's shell is plugin-shaped: the bar, the panels,
+# the overlays are all plugins. A few of them are Ymir's own organs rendered on
+# the desktop — herdr (Þjazi), Hermes (our worker runtime), and skills (the Galdr
+# family). This suggests them at install, and installs only what the Allfather
+# accepts.
+#
+# Installing is Omarchy's own verb — never a raw clone:
+#   omarchy plugin add <repo> [--enable]   ·   omarchy plugin remove <id>
+# (Omarchy docs: "A plugin is a git repo with a manifest.json at its root.")
+#
+# Usage:
+#   bin/omarchy-plugins.sh list                  # what Ymir suggests
+#   bin/omarchy-plugins.sh installed             # what is present now
+#   bin/omarchy-plugins.sh suggest [--yes]       # offer them; install on consent
+#   bin/omarchy-plugins.sh add <id>              # install one (with consent unless --yes)
+#   bin/omarchy-plugins.sh --version
+#
+# Consent: nothing is installed without an explicit yes (or --yes). These are
+# third-party plugins that run unsandboxed inside the Omarchy shell — the registry
+# itself says it "validates listings, not plugin security".
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# The roots that live OUTSIDE the code tree: this machine's records and the
+# runtime state belong to the home the operator chose at installation, never in
+# the tree — a packaged install replaces its tree on upgrade (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_state_dir YMIR_STATE_DIR
+hoard_data_dir YMIR_DATA_DIR
+YES=0
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+ACTION="${1:-list}"; shift || true
+[ "${1:-}" = "--yes" ] && YES=1
+[ "${1:-}" = "-y" ] && YES=1
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# id | name | why it earns a place in Ymir's suggestion list
+catalog() {
+  cat <<'PLUGINS'
+io.github.eszanon.herdr|Herdr Watch|herdr agents in the bar, flags the ones waiting on you — Þjazi made visible
+io.github.mbot11.hermes-deck|Hermes Deck|live Hermes companion: status, sessions, usage, controls — Hermes is our worker runtime
+firstpick.skill-manager|Skill Manager|links local skills across Pi, OpenCode, Claude Code, Cursor, Codex — the Galdr family on every harness
+io.github.fabean.herdr|Herdr|monitor herdr agent activity and status from the bar
+stappmus.udder|Udder|all your herdr agents in the bar, notified when one finishes
+mrpbennett.herdr-agents|Herdr Agents|every agent's state and current activity in the bar
+io.github.andy-spike.herdr-theme-sync|Herdr Theme Sync|keeps herdr colors in step with the Omarchy theme
+yordanbuilds.rig|Rig|project stacks for herdr — one JSON file and the workspace is up
+tsouth89.omcp|OMCP|turn this desktop into an MCP server other agents can drive
+PLUGINS
+}
+
+installed_plugins() {
+  have omarchy || return 0
+  # omarchy plugin list --json is the structured form; fall back to plain text.
+  if omarchy plugin list --json >/dev/null 2>&1; then
+    omarchy plugin list --json 2>/dev/null | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+    items = d.get("plugins") if isinstance(d, dict) else d
+    if isinstance(items, dict): items = list(items.values())
+    for it in (items or []):
+        print(it.get("id") or it.get("name") or "")
+except Exception:
+    pass' 2>/dev/null
+  else
+    omarchy plugin list 2>/dev/null | awk '{print $1}'
+  fi
+}
+
+is_installed() {  # <id>
+  installed_plugins | grep -qxF "$1" 2>/dev/null
+}
+
+repo_for() {  # <id> — read the repo from the registry's own catalog when reachable
+  local id=$1 cache="$YMIR_STATE_DIR/omarchy-catalog.json"
+  if [ -r "$cache" ]; then
+    python3 - "$cache" "$id" <<'PY' 2>/dev/null
+import json,sys
+try:
+    d=json.load(open(sys.argv[1])); items=d.get("plugins", d)
+    if isinstance(items, dict): items=list(items.values())
+    for it in items:
+        if it.get("id")==sys.argv[2]:
+            print(it.get("repo") or ""); break
+except Exception:
+    pass
+PY
+  fi
+}
+
+case "$ACTION" in
+  list)
+    printf 'omarchy-plugins[%d]{id,name,why}:\n' "$(catalog | grep -c .)"
+    while IFS='|' read -r id name why; do
+      [ -n "$id" ] || continue
+      printf '  "%s","%s","%s"\n' "$id" "$name" "$why"
+    done < <(catalog)
+    printf 'install: bin/omarchy-plugins.sh add <id>   (Omarchy installs via `omarchy plugin add`)\n'
+    ;;
+  installed)
+    if ! have omarchy; then printf 'omarchy-plugins[1]{state}:\n  "not an Omarchy host"\n'; exit 0; fi
+    mapfile -t have_ids < <(installed_plugins)
+    printf 'omarchy-plugins[%d]{id,present}:\n' "${#have_ids[@]}"
+    for id in "${have_ids[@]}"; do [ -n "$id" ] && printf '  "%s","yes"\n' "$id"; done
+    ;;
+  suggest)
+    if ! have omarchy; then printf 'omarchy-plugins[1]{state}:\n  "skipped — not an Omarchy host"\n'; exit 0; fi
+    printf 'Ymir suggests these Omarchy plugins — third-party code that runs inside your shell:\n\n'
+    while IFS='|' read -r id name why; do
+      [ -n "$id" ] || continue
+      if is_installed "$id"; then printf '  [have] %-32s %s\n' "$name" "$why"
+      else printf '  [ -- ] %-32s %s\n' "$name" "$why"; fi
+    done < <(catalog)
+    printf '\nEach is Omarchy-verified as a listing, not audited for safety. Install one at a time:\n'
+    printf '  bin/omarchy-plugins.sh add <id>\n'
+    if [ "$YES" = 1 ]; then
+      while IFS='|' read -r id name why; do
+        [ -n "$id" ] || continue
+        is_installed "$id" && continue
+        "$SCRIPT_DIR/omarchy-plugins.sh" add "$id" --yes || true
+      done < <(catalog)
+    fi
+    ;;
+  add)
+    id="${1:-}"; shift || true
+    [ -n "$id" ] || { printf 'error: add needs a plugin id\nhelp: bin/omarchy-plugins.sh list\n' >&2; exit 2; }
+    [ "${1:-}" = "--yes" ] && YES=1
+    have omarchy || { printf 'error: not an Omarchy host (no `omarchy` command)\n' >&2; exit 1; }
+    if is_installed "$id"; then
+      printf 'omarchy-plugins[1]{id,state}:\n  "%s","already installed"\n' "$id"; exit 0
+    fi
+    # Resolve the repo from the registry catalog; refresh it if absent.
+    cache="$YMIR_STATE_DIR/omarchy-catalog.json"
+    if [ ! -r "$cache" ] && have curl; then
+      mkdir -p "$(dirname "$cache")"
+      curl -fsS --max-time 25 https://plugins.omarchy.org/catalog.json -o "$cache" 2>/dev/null || true
+    fi
+    repo="$(repo_for "$id")"
+    if [ -z "$repo" ]; then
+      printf 'error: cannot resolve the repository for %s\nhelp: check the id (bin/omarchy-plugins.sh list), or install by repo:\n' "$id" >&2
+      printf '      omarchy plugin add <git-url> --enable\n' >&2
+      exit 1
+    fi
+    if [ "$YES" != 1 ]; then
+      if [ ! -t 0 ]; then
+        printf 'error: refusing to install %s without --yes\nhelp: bin/omarchy-plugins.sh add %s --yes\n' "$id" "$id" >&2
+        exit 3
+      fi
+      printf 'Install %s from %s? It runs unsandboxed inside your Omarchy shell. [y/N] ' "$id" "$repo"
+      read -r reply || reply=""
+      case "$reply" in y|Y|yes|YES) ;; *) printf 'skipped.\n'; exit 0 ;; esac
+    fi
+    # Omarchy's own installer demands consent too (`--yes` to it). We already took
+    # the Allfather's consent above, so pass it through.
+    # Private tempfile (was a predictable /tmp/<name>.$$ path — a symlink/race risk).
+    log="$(mktemp)" || { printf 'error: could not create a temp file\n' >&2; exit 1; }
+    if omarchy plugin add "$repo" --enable --yes >"$log" 2>&1; then
+      rm -f "$log"
+      printf 'omarchy-plugins[1]{id,state,repo}:\n  "%s","installed","%s"\n' "$id" "$repo"
+    else
+      printf 'omarchy-plugins[1]{id,state}:\n  "%s","install failed"\n' "$id"
+      printf 'help: omarchy said:\n' >&2
+      tail -5 "$log" >&2 2>/dev/null || true
+      rm -f "$log"
+      exit 1
+    fi
+    ;;
+  *) printf 'error: unknown action %s\nhelp: bin/omarchy-plugins.sh [list|installed|suggest|add]\n' "$ACTION" >&2; exit 2 ;;
+esac

package/bin/omarchy-sense.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# omarchy-sense.sh — learn the Allfather's Omarchy machine.
+#
+# Ymir runs on an Omarchy host, and that host changes: packages get installed,
+# configs get edited, Omarchy itself updates. This records what is stable, what
+# changed since the last look, and when Omarchy itself moved — so the agent can
+# help with *this* machine rather than a generic one.
+#
+# It is a sensor, not a fixer: it observes, records, and reports. Nothing on the
+# user's machine is modified.
+#
+# Usage:
+#   bin/omarchy-sense.sh observe [--quiet]   # record the current state, diff vs last
+#   bin/omarchy-sense.sh status              # show the latest snapshot + last change
+#   bin/omarchy-sense.sh --version
+#
+# State: state/omarchy-setup.json (gitignored — this is per-user, per-machine).
+# Output: Galdr TOON.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# The roots that live OUTSIDE the code tree: this machine's records and the
+# runtime state belong to the home the operator chose at installation, never in
+# the tree — a packaged install replaces its tree on upgrade (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_state_dir YMIR_STATE_DIR
+hoard_data_dir YMIR_DATA_DIR
+STATE_DIR="${BROKK_STATE_OVERRIDE:-$YMIR_STATE_DIR}"
+SNAP="$STATE_DIR/omarchy-setup.json"
+
+# Rule 05: this is the OMARCHY layer's sensor, so it is gated on its host. Ymir
+# is Omarchy-first — that layer is first-class — but first is not only: this
+# script observes an Omarchy machine, and on any other host it skips cleanly
+# and points at the portable sensor instead of recording the wrong machine.
+if ! { command -v omarchy >/dev/null 2>&1 || [ -d "$HOME/.local/share/omarchy" ]; }; then
+  printf 'omarchy-sense[1]{step,status,detail}:\n'
+  printf '  "sensor","SKIP","not an Omarchy host — this layer applies where Omarchy is; run bin/host-sense.sh for THIS machine"\n'
+  exit 0
+fi
+QUIET=0
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+ACTION="${1:-observe}"; shift || true
+[ "${1:-}" = "--quiet" ] && QUIET=1
+
+is_omarchy() { [ -d /usr/share/omarchy ]; }
+
+# A stable, comparable fingerprint of the machine. Keep keys short (TOON).
+snapshot() {
+  local ov="" pkgs cnf monitors scale wm
+  is_omarchy && ov="$(omarchy version 2>/dev/null | head -1)"
+  # Explicitly installed packages (the user's own choices, not the base image).
+  pkgs="$(pacman -Qe 2>/dev/null | wc -l | tr -d ' ')"
+  # The user's config surface: what they have customised.
+  cnf="$(find "$HOME/.config" -maxdepth 3 -type f \
+          \( -name '*.lua' -o -name 'shell.json' -o -name '*.conf' -o -name '*.jsonc' \) \
+          2>/dev/null | wc -l | tr -d ' ')"
+  monitors="$(hyprctl monitors -j 2>/dev/null \
+    | python3 -c 'import json,sys
+try:
+  m=json.load(sys.stdin); print(len(m))
+except Exception: print(0)' 2>/dev/null || echo 0)"
+  scale="$(hyprctl monitors -j 2>/dev/null \
+    | python3 -c 'import json,sys
+try:
+  m=json.load(sys.stdin); print(m[0].get("scale") if m else 0)
+except Exception: print(0)' 2>/dev/null || echo 0)"
+  wm="${XDG_CURRENT_DESKTOP:-unknown}"
+  python3 - "$ov" "$pkgs" "$cnf" "$monitors" "$scale" "$wm" <<'PY'
+import json, sys
+ov, pkgs, cnf, monitors, scale, wm = sys.argv[1:7]
+print(json.dumps({
+  "omarchy": ov,
+  "explicit_pkgs": int(pkgs or 0),
+  "config_files": int(cnf or 0),
+  "monitors": int(monitors or 0),
+  "scale": scale,
+  "wm": wm,
+}, sort_keys=True))
+PY
+}
+
+observe() {
+  mkdir -p "$STATE_DIR"
+  local now; now="$(snapshot)"
+  local prev="{}"
+  [ -r "$SNAP" ] && prev="$(cat "$SNAP")"
+
+  # Diff the scalars that matter, so we can report what the user changed.
+  local report
+  report="$(python3 - "$prev" "$now" <<'PY'
+import json, sys
+prev = json.loads(sys.argv[1] or "{}")
+now = json.loads(sys.argv[2] or "{}")
+keys = ["omarchy", "explicit_pkgs", "config_files", "monitors", "scale", "wm"]
+changes = []
+for k in keys:
+    if k in prev and prev[k] != now.get(k):
+        changes.append((k, prev[k], now.get(k)))
+print(json.dumps({"changes": changes, "now": now}))
+PY
+)"
+  # Persist the new snapshot with a timestamp (the snapshot itself stays comparable).
+  python3 - "$SNAP" "$now" <<'PY'
+import json, sys, datetime, os, tempfile
+path, now = sys.argv[1], json.loads(sys.argv[2])
+now["observed_at"] = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+d = os.path.dirname(path) or "."
+fd, tmp = tempfile.mkstemp(dir=d)
+with os.fdopen(fd, "w") as f:
+    json.dump(now, f, indent=2, sort_keys=True)
+os.replace(tmp, path)
+PY
+
+  [ "$QUIET" = 1 ] && return 0
+  printf 'omarchy-sense[1]{omarchy,monitors,scale,configs,pkgs,changes}:\n'
+  python3 - "$report" "$SNAP" <<'PY'
+import json, sys
+rep = json.loads(sys.argv[1])
+n = rep["now"]
+ch = rep["changes"]
+print(f'  "{n.get("omarchy") or "not-omarchy"}",{n.get("monitors",0)},"{n.get("scale",0)}",'
+      f'{n.get("config_files",0)},{n.get("explicit_pkgs",0)},{len(ch)}')
+PY
+  python3 - "$report" <<'PY'
+import json, sys
+rep = json.loads(sys.argv[1])
+for k, a, b in rep["changes"]:
+    print(f'changed[1]{{field,was,now}}:\n  "{k}","{a}","{b}"')
+PY
+}
+
+case "$ACTION" in
+  observe) observe ;;
+  status)
+    if [ -r "$SNAP" ]; then
+      printf 'omarchy-sense[1]{snapshot}:\n'
+      python3 - "$SNAP" <<'PY'
+import json, sys
+d = json.load(open(sys.argv[1]))
+print(f'  "{d.get("omarchy") or "not-omarchy"} · monitors={d.get("monitors")} '
+      f'scale={d.get("scale")} configs={d.get("config_files")} '
+      f'pkgs={d.get("explicit_pkgs")} · seen {d.get("observed_at")}"')
+PY
+    else
+      printf 'omarchy-sense[1]{snapshot}:\n  "none yet — run bin/omarchy-sense.sh observe"\n'
+    fi
+    ;;
+  *) printf 'error: unknown action %s\nhelp: bin/omarchy-sense.sh [observe|status]\n' "$1" >&2; exit 2 ;;
+esac

package/bin/perm-guard.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# perm-guard.sh — flag agent profiles whose permissions are self-defeating.
+# The headline case: a flat `bash: allow` gives a total shell, so any
+# `edit: deny` / `write: deny` on the same agent stops nothing.
+#
+#   bin/perm-guard.sh            # report (exit 0)
+#   bin/perm-guard.sh --strict   # exit 1 if any flat bash allowance exists
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+STRICT=0; [ "${1:-}" = "--strict" ] && STRICT=1
+
+hits=0
+printf 'perm-guard{agent,issue}:\n'
+for f in "$ROOT"/.agents/agents/*.md; do
+  [ -e "$f" ] || continue
+  name="$(sed -n 's/^name: *//p' "$f" | head -1)"; [ -n "$name" ] || name="$(basename "$f" .md)"
+  if grep -Eq '^  bash: *allow *$' "$f"; then
+    if grep -Eq '^  (edit|write): *deny' "$f"; then
+      printf '  "%s","flat bash:allow defeats edit/write deny"\n' "$name"
+    else
+      printf '  "%s","flat bash:allow (total shell)"\n' "$name"
+    fi
+    hits=$((hits+1))
+  fi
+done
+[ "$hits" -gt 0 ] || printf '  "none","all agents use a patterned bash"\n'
+[ "$STRICT" = 1 ] && [ "$hits" -gt 0 ] && exit 1
+exit 0

package/bin/pi-agent.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# pi-agent.sh — run a Ymir agent on a LOCAL model with ITS OWN persona/mission
+# (not Brokk's), loading only the skills it needs. Reusable for users.
+#
+#   bin/pi-agent.sh <agent> "<task>"
+#   bin/pi-agent.sh hnoss "design a hero" --skill .agents/skills/hnoss-design
+#   bin/pi-agent.sh sindri "fix the bug" -m qwen3.6-35b-q4_k_s
+#
+# It loads the agent's canonical profile body as the system prompt, disables the
+# root AGENTS.md / global skills / Ymir persona, and adds the agent's own skill
+# (if it has one) plus any --skill paths. Local models run one at a time — see
+# bin/local-model-lock.sh.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+PROVIDER="${PI_LOCAL_PROVIDER:-llama-cpp}"
+MODEL="${PI_LOCAL_MODEL:-frontend-design-expert-8b@q4_k_m}"
+AGENT=""; TASK=""; SKILLS=()
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,10p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+
+[ $# -gt 0 ] || { printf 'error: usage: bin/pi-agent.sh <agent> "<task>"\n' >&2; exit 2; }
+AGENT="$1"; shift
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -m|--model) MODEL=${2-}; shift 2 ;;
+    -p|--provider) PROVIDER=${2-}; shift 2 ;;
+    --skill) SKILLS+=("${2-}"); shift 2 ;;
+    *) TASK="$TASK${TASK:+ }$1"; shift ;;
+  esac
+done
+[ -n "$TASK" ] || { printf 'error: %s needs a task\n' "$AGENT" >&2; exit 2; }
+
+# 1. the agent's canonical profile (persona + mission) by `name:`.
+PROFILE=""
+for f in "$ROOT"/.agents/agents/*.md; do
+  [ -e "$f" ] || continue
+  grep -qx "name: $AGENT" "$f" && { PROFILE="$f"; break; }
+done
+[ -n "$PROFILE" ] || { printf 'error: no profile named %s\nhelp: bin/agents-config.sh show\n' "$AGENT" >&2; exit 1; }
+
+# 2. persona = the profile body (everything after the frontmatter).
+PERSONA="$(python3 - "$PROFILE" <<'PY'
+import sys
+t = open(sys.argv[1]).read()
+parts = t.split("---")
+print("---".join(parts[2:]).strip() if len(parts) >= 3 else t)
+PY
+)"
+
+# 3. the agent's own skill, if it has one (folder is now figure-function,
+#    e.g. hnoss-design), plus any explicit --skill.
+for sk in "$ROOT/.agents/skills/$AGENT" "$ROOT"/.agents/skills/"$AGENT"-*; do
+  [ -f "$sk/SKILL.md" ] && { SKILLS+=("$sk"); break; }
+done
+
+command -v pi >/dev/null 2>&1 || { printf 'error: pi is not on PATH\n' >&2; exit 1; }
+
+args=(--print --no-context-files --no-skills --system-prompt "$PERSONA" --model "$PROVIDER/$MODEL")
+for s in "${SKILLS[@]:-}"; do [ -n "$s" ] && args+=(--skill "$s"); done
+
+printf 'pi-agent[1]{agent,provider,model,skills}:\n  "%s","%s","%s","%s"\n' \
+  "$AGENT" "$PROVIDER" "$MODEL" "$(IFS=,; echo "${SKILLS[*]:-none}")" >&2
+# Local inference is serialized per host (one model at a time by default).
+exec "$SCRIPT_DIR/local-model-lock.sh" pi "${args[@]}" "$TASK"

package/bin/pi-ensure.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# pi-ensure.sh — ensure the Pi coding agent and the Ymir-required Pi packages.
+#
+# Pi has no native MCP, no native web access, and no built-in local-model bridge:
+# those arrive as Pi packages. This guarantees the three Ymir depends on:
+#   npm:pi-mcp-adapter  — MCP servers (from mcp.json: a2abridge, engram)
+#   npm:pi-web-access   — web fetch/search tools
+#   npm:pi-lmstudio     — LM Studio / local model provider
+#
+# Usage:
+#   pi-ensure.sh status            # pi + which packages are present
+#   pi-ensure.sh ensure [--install]
+#   pi-ensure.sh install
+#   pi-ensure.sh --version
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+SETTINGS="${PI_SETTINGS:-$HOME/.pi/agent/settings.json}"
+REQUIRED=(pi-mcp-adapter pi-web-access pi-lmstudio)
+
+CMD="status"; INSTALL=0
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+case "$1" in status|ensure|install) CMD=$1; shift ;; *) printf 'error: unknown command %s\nhelp: pi-ensure.sh [status|ensure|install]\n' "$1" >&2; exit 2 ;; esac
+while [ $# -gt 0 ]; do case "$1" in --install) INSTALL=1; shift ;; *) shift ;; esac; done
+[ "$CMD" = install ] && INSTALL=1
+
+have() { command -v "$1" >/dev/null 2>&1; }
+pi_bin() { command -v pi 2>/dev/null || true; }
+pkg_present() { grep -q "npm:$1" "$SETTINGS" 2>/dev/null; }
+
+install_pi() {
+  have pi && return 0
+  if have mise; then
+    mise install pi@latest >/dev/null 2>&1 || mise use -g pi@latest >/dev/null 2>&1 || true
+  fi
+  have pi
+}
+
+install_pkgs() {
+  local p
+  have pi || return 1
+  for p in "${REQUIRED[@]}"; do
+    pkg_present "$p" && continue
+    pi install "npm:$p" >/dev/null 2>&1 || true
+  done
+  return 0
+}
+
+report() {
+  local bin ver p rows="" missing=0
+  bin="$(pi_bin)"; ver="$(pi --version 2>/dev/null | head -1)"
+  printf 'pi[1]{bin,version}:\n  "%s","%s"\n' "${bin:-none}" "${ver:-none}"
+  for p in "${REQUIRED[@]}"; do
+    if pkg_present "$p"; then rows="${rows}  \"${p}\",\"present\"\n"; else rows="${rows}  \"${p}\",\"absent\"\n"; missing=$((missing+1)); fi
+  done
+  printf 'pi-packages[%d]{package,state}:\n' "${#REQUIRED[@]}"
+  printf '%b' "$rows"
+  return "$missing"
+}
+
+case "$CMD" in
+  status)
+    report || exit 1
+    ;;
+  ensure)
+    if ! have pi && [ "$INSTALL" = 1 ]; then install_pi || true; fi
+    if have pi && [ "$INSTALL" = 1 ]; then install_pkgs || true; fi
+    if report; then exit 0; else exit 1; fi
+    ;;
+  install)
+    install_pi || { printf 'error: pi could not be installed (need mise or npm)\n' >&2; exit 1; }
+    install_pkgs
+    report && exit 0 || exit 1
+    ;;
+esac

package/bin/pi-local.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# pi-local.sh — run a Pi agent on a LOCAL model, reusable.
+#
+#   bin/pi-local.sh "<prompt>"                       # default local model
+#   bin/pi-local.sh -m <model> "<prompt>"            # another llama.cpp model
+#   PI_LOCAL_MODEL=... bin/pi-local.sh "<prompt>"
+#
+# The model id is the EXACT llama.cpp served id (…@quant). Defaults come from
+# config/agents.yaml resolution; override with -m/--model or the env vars.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+PROVIDER="${PI_LOCAL_PROVIDER:-llama-cpp}"
+MODEL="${PI_LOCAL_MODEL:-frontend-design-expert-8b@q4_k_m}"
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,9p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -m|--model) MODEL=${2-}; shift 2 ;;
+    -p|--provider) PROVIDER=${2-}; shift 2 ;;
+    --) shift; break ;;
+    -*) printf 'error: unknown flag %s\n' "$1" >&2; exit 2 ;;
+    *) break ;;
+  esac
+done
+PROMPT="${*:-}"
+[ -n "$PROMPT" ] || { printf 'error: usage: bin/pi-local.sh [-m model] "<prompt>"\n' >&2; exit 2; }
+
+command -v pi >/dev/null 2>&1 || { printf 'error: pi is not on PATH\n' >&2; exit 1; }
+
+printf 'pi-local[1]{provider,model}:\n  "%s","%s"\n' "$PROVIDER" "$MODEL" >&2
+exec "$SCRIPT_DIR/local-model-lock.sh" pi --print --model "$PROVIDER/$MODEL" "$PROMPT"

package/bin/pi-model-agnostic.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# pi-model-agnostic — pi must not EXPECT any model. Local and online are peers.
+#
+# The law (Allfather, 2026-09-17): a seat that answers is used; a seat that does not
+# must not stop pi from starting. pi was failing at launch because providers pointed at
+# local ports with nothing behind them:
+#   [llama-cpp] failed to reach http://localhost:8080/v1/models: fetch failed
+# An unreachable local seat is a SKIP, not an error.
+#
+# This prunes unreachable LOCAL providers from pi's models config, keeping every seat
+# that answers and every online provider untouched.
+#
+#   bin/pi-model-agnostic.sh            # report and prune
+#   bin/pi-model-agnostic.sh --dry-run  # report only
+set -euo pipefail
+
+CFG="${PI_MODELS_JSON:-$HOME/.pi/agent/models.json}"
+DRY=0
+[ "${1:-}" = "--dry-run" ] && DRY=1
+[ -f "$CFG" ] || { printf 'error: no pi models config at %s\nhelp: set PI_MODELS_JSON\n' "$CFG" >&2; exit 1; }
+
+CFG="$CFG" DRY="$DRY" python3 - <<'INNER'
+import json, os, shutil, sys, time, urllib.request
+
+cfg = os.environ["CFG"]
+dry = os.environ.get("DRY") == "1"
+d = json.load(open(cfg))
+providers = d.get("providers", {})
+
+def reachable(url):
+    if not url:
+        return False
+    probe = url.rstrip("/")
+    if not probe.endswith("/v1"):
+        probe += "/v1"
+    try:
+        with urllib.request.urlopen(probe + "/models", timeout=3) as r:
+            return r.status == 200
+    except Exception:
+        return False
+
+kept, dropped = [], []
+for name, prov in providers.items():
+    base = str(prov.get("baseUrl", ""))
+    local = ("127.0.0.1" in base) or ("localhost" in base) or ("0.0.0.0" in base)
+    if local and not reachable(base):
+        dropped.append((name, base))
+    else:
+        kept.append(name)
+
+print("pi_models[%d]{provider,base,verdict}:" % (len(kept) + len(dropped)))
+for n in kept:
+    print('  "%s","%s","kept"' % (n, providers[n].get("baseUrl", "")))
+for n, b in dropped:
+    print('  "%s","%s","unreachable local seat - pruned"' % (n, b))
+
+if dropped and not dry:
+    shutil.copy2(cfg, cfg + ".bak-" + time.strftime("%Y%m%d%H%M%S"))
+    d["providers"] = {k: v for k, v in providers.items() if k in kept}
+    dm = d.get("defaultProvider")
+    if dm and dm not in kept and kept:
+        d["defaultProvider"] = kept[0]
+        ids = (d["providers"][kept[0]].get("models") or [{}])
+        if ids and ids[0].get("id"):
+            d["defaultModel"] = ids[0]["id"]
+        print("  default -> %s / %s" % (d.get("defaultProvider"), d.get("defaultModel")))
+    json.dump(d, open(cfg, "w"), indent=2)
+    print("pi_models: %d pruned, backup beside the config" % len(dropped))
+elif dry:
+    print("pi_models: dry run - nothing written")
+INNER