V0.7.0 shell contract (#54)

server/events/bus_test.go

@@ -236,3 +236,29 @@ func TestToolResultRouteBoth(t *testing.T) {
 		t.Error("tool.result.* should route DirBoth (filtered by WS subscriber, not routing table)")
 	}
 }
+
+func TestShellContractEventRoutes(t *testing.T) {
+	// package.changed — broadcast to all clients
+	if !ShouldSendToClient("package.changed") {
+		t.Error("package.changed should be sent to client")
+	}
+	if ShouldAcceptFromClient("package.changed") {
+		t.Error("package.changed should NOT be accepted from client")
+	}
+
+	// auth.changed — targeted to specific user
+	if !ShouldSendToClient("auth.changed") {
+		t.Error("auth.changed should be sent to client")
+	}
+	if ShouldAcceptFromClient("auth.changed") {
+		t.Error("auth.changed should NOT be accepted from client")
+	}
+
+	// notification.all_read — targeted to specific user
+	if !ShouldSendToClient("notification.all_read") {
+		t.Error("notification.all_read should be sent to client")
+	}
+	if ShouldAcceptFromClient("notification.all_read") {
+		t.Error("notification.all_read should NOT be accepted from client")
+	}
+}

server/events/types.go

@@ -51,8 +51,15 @@ var routeTable = map[string]Direction{
 	"role.fallback":     DirToClient,
 
 	// Notifications
-	"notification.new":  DirToClient, // targeted via Hub.PublishToUser, not room-based
-	"notification.read": DirToClient, // badge sync across tabs
+	"notification.new":      DirToClient, // targeted via Hub.PublishToUser, not room-based
+	"notification.read":     DirToClient, // badge sync across tabs
+	"notification.all_read": DirToClient, // mark-all-read badge sync
+
+	// Package lifecycle (broadcast to all clients)
+	"package.changed": DirToClient, // install/uninstall/enable/disable
+
+	// Auth changes (targeted to affected user)
+	"auth.changed": DirToClient, // role/membership change → menu refresh
 
 	// Workspace
 

server/events/ws.go

@@ -173,6 +173,12 @@ func (h *Hub) IsConnected(userID string) bool {
 	return false
 }
 
+// Broadcast sends an event to all connected clients via the bus.
+// No TargetUserID — every WS subscriber receives it.
+func (h *Hub) Broadcast(event Event) {
+	h.bus.Publish(event)
+}
+
 // PublishToUser sends an event to a specific user via the bus.
 // All replicas receive the event; only the one with the user's connection delivers it.
 func (h *Hub) PublishToUser(userID string, event Event) {

server/handlers/groups.go

@@ -4,11 +4,13 @@ import (
 	"database/sql"
 	"errors"
 	"net/http"
+	"time"
 
 	"github.com/gin-gonic/gin"
 
 	"armature/auth"
 	"armature/database"
+	"armature/events"
 	"armature/models"
 	"armature/notifications"
 	"armature/store"
@@ -43,12 +45,30 @@ type setResourceGrantRequest struct {
 
 type GroupHandler struct {
 	stores store.Stores
+	hub    *events.Hub
 }
 
 func NewGroupHandler(s store.Stores) *GroupHandler {
 	return &GroupHandler{stores: s}
 }
 
+// SetHub attaches the event hub for auth change notifications.
+func (h *GroupHandler) SetHub(hub *events.Hub) {
+	h.hub = hub
+}
+
+// notifyAuthChanged sends an auth.changed event to a specific user.
+func (h *GroupHandler) notifyAuthChanged(userID, reason string) {
+	if h.hub == nil {
+		return
+	}
+	h.hub.PublishToUser(userID, events.Event{
+		Label:   "auth.changed",
+		Payload: events.MustJSON(map[string]string{"reason": reason}),
+		Ts:      time.Now().UnixMilli(),
+	})
+}
+
 // ── Admin: List All Groups ──────────────────
 
 func (h *GroupHandler) ListGroups(c *gin.Context) {
@@ -249,6 +269,7 @@ func (h *GroupHandler) AddMember(c *gin.Context) {
 	}
 
 	c.JSON(http.StatusOK, gin.H{"ok": true})
+	h.notifyAuthChanged(req.UserID, "group_member_added")
 	AuditLog(h.stores.Audit, c, "group.member.add", "group", groupID, map[string]interface{}{
 		"user_id": req.UserID,
 	})
@@ -279,6 +300,7 @@ func (h *GroupHandler) RemoveMember(c *gin.Context) {
 	}
 
 	c.JSON(http.StatusOK, gin.H{"ok": true})
+	h.notifyAuthChanged(userID, "group_member_removed")
 	AuditLog(h.stores.Audit, c, "group.member.remove", "group", groupID, map[string]interface{}{
 		"user_id": userID,
 	})

server/handlers/notifications.go

@@ -137,10 +137,9 @@ func (h *NotificationHandler) MarkAllRead(c *gin.Context) {
 
 	// Sync badge across tabs
 	if h.hub != nil {
-		payload, _ := json.Marshal(map[string]string{"action": "mark_all_read"})
 		h.hub.PublishToUser(userID, events.Event{
-			Label:   "notification.read",
-			Payload: payload,
+			Label:   "notification.all_read",
+			Payload: events.MustJSON(map[string]string{}),
 			Ts:      time.Now().UnixMilli(),
 		})
 	}

server/handlers/packages.go

@@ -11,11 +11,13 @@ import (
 	"path/filepath"
 	"regexp"
 	"strings"
+	"time"
 
 	"github.com/gin-gonic/gin"
 	"go.starlark.net/starlark"
 
 	"armature/database"
+	"armature/events"
 	"armature/models"
 	"armature/sandbox"
 	"armature/store"
@@ -34,6 +36,7 @@ type PackageHandler struct {
 	bundledDir     string           // e.g. /app/bundled-packages — .pkg archive source
 	sandbox        *sandbox.Sandbox
 	runner         *sandbox.Runner
+	hub            *events.Hub
 }
 
 func NewPackageHandler(s store.Stores, packagesDir ...string) *PackageHandler {
@@ -60,6 +63,23 @@ func (h *PackageHandler) SetRunner(r *sandbox.Runner) {
 	h.runner = r
 }
 
+// SetHub attaches the event hub for broadcasting package lifecycle events.
+func (h *PackageHandler) SetHub(hub *events.Hub) {
+	h.hub = hub
+}
+
+// broadcastPackageChanged emits a package.changed event to all clients.
+func (h *PackageHandler) broadcastPackageChanged(action, id string) {
+	if h.hub == nil {
+		return
+	}
+	h.hub.Broadcast(events.Event{
+		Label:   "package.changed",
+		Payload: events.MustJSON(map[string]string{"action": action, "id": id}),
+		Ts:      time.Now().UnixMilli(),
+	})
+}
+
 // ListPackages returns all registered packages.
 // GET /api/v1/admin/packages
 func (h *PackageHandler) ListPackages(c *gin.Context) {
@@ -116,6 +136,7 @@ func (h *PackageHandler) EnablePackage(c *gin.Context) {
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"id": id, "enabled": true})
+	h.broadcastPackageChanged("enabled", id)
 }
 
 // DisablePackage disables a package. Admin cannot be disabled.
@@ -133,6 +154,7 @@ func (h *PackageHandler) DisablePackage(c *gin.Context) {
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"id": id, "enabled": false})
+	h.broadcastPackageChanged("disabled", id)
 }
 
 // DeletePackage uninstalls a package. Core packages cannot be deleted.
@@ -180,6 +202,7 @@ func (h *PackageHandler) DeletePackage(c *gin.Context) {
 	}
 
 	c.JSON(http.StatusOK, gin.H{"id": id, "deleted": true})
+	h.broadcastPackageChanged("deleted", id)
 }
 
 // InstallPackage uploads and installs a .pkg/.surface archive.
@@ -586,6 +609,7 @@ func (h *PackageHandler) InstallPackage(c *gin.Context) {
 		resp["status"] = "dormant"
 	}
 	c.JSON(http.StatusOK, resp)
+	h.broadcastPackageChanged("installed", pkgID)
 }
 
 // extractableRelPath returns the relative path for a zip entry if it
@@ -1073,6 +1097,7 @@ func (h *PackageHandler) UpdatePackage(c *gin.Context) {
 		"previous_version": previousVersion,
 		"changes":          schemaChanges,
 	})
+	h.broadcastPackageChanged("updated", pkgID)
 }
 
 // mergePackageSettings merges existing settings with a new manifest's settings schema.

server/handlers/teams.go

@@ -7,11 +7,13 @@ import (
 	"fmt"
 	"net/http"
 	"strconv"
+	"time"
 
 	"github.com/gin-gonic/gin"
 
 	"armature/crypto"
 	"armature/database"
+	"armature/events"
 	"armature/models"
 	"armature/store"
 )
@@ -44,12 +46,30 @@ type updateMemberRequest struct {
 type TeamHandler struct{
 	stores store.Stores
 	vault  *crypto.KeyResolver
+	hub    *events.Hub
 }
 
 func NewTeamHandler(s store.Stores, vault *crypto.KeyResolver) *TeamHandler {
 	return &TeamHandler{stores: s, vault: vault}
 }
 
+// SetHub attaches the event hub for auth change notifications.
+func (h *TeamHandler) SetHub(hub *events.Hub) {
+	h.hub = hub
+}
+
+// notifyAuthChanged sends an auth.changed event to a specific user.
+func (h *TeamHandler) notifyAuthChanged(userID, reason string) {
+	if h.hub == nil {
+		return
+	}
+	h.hub.PublishToUser(userID, events.Event{
+		Label:   "auth.changed",
+		Payload: events.MustJSON(map[string]string{"reason": reason}),
+		Ts:      time.Now().UnixMilli(),
+	})
+}
+
 // ── Admin: List All Teams ───────────────────
 
 func (h *TeamHandler) ListTeams(c *gin.Context) {
@@ -278,6 +298,7 @@ func (h *TeamHandler) AddMember(c *gin.Context) {
 	}
 
 	c.JSON(http.StatusCreated, gin.H{"id": id})
+	h.notifyAuthChanged(req.UserID, "team_member_added")
 	AuditLog(h.stores.Audit, c, "team.add_member", "team", getTeamID(c), map[string]interface{}{
 		"user_id": req.UserID, "role": req.Role,
 	})
@@ -312,6 +333,9 @@ func (h *TeamHandler) UpdateMember(c *gin.Context) {
 	}
 
 	c.JSON(http.StatusOK, gin.H{"ok": true})
+	if uid := h.memberUserID(c.Request.Context(), teamID, memberID); uid != "" {
+		h.notifyAuthChanged(uid, "team_role")
+	}
 	AuditLog(h.stores.Audit, c, "team.update_member", "team", getTeamID(c), map[string]interface{}{
 		"member_id": memberID, "role": req.Role,
 	})
@@ -323,6 +347,9 @@ func (h *TeamHandler) RemoveMember(c *gin.Context) {
 	teamID := getTeamID(c)
 	memberID := c.Param("memberId")
 
+	// Look up user_id before delete for auth notification
+	affectedUID := h.memberUserID(c.Request.Context(), teamID, memberID)
+
 	n, err := h.stores.Teams.DeleteMemberByID(c.Request.Context(), memberID, teamID)
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "remove failed"})
@@ -334,6 +361,9 @@ func (h *TeamHandler) RemoveMember(c *gin.Context) {
 	}
 
 	c.JSON(http.StatusOK, gin.H{"ok": true})
+	if affectedUID != "" {
+		h.notifyAuthChanged(affectedUID, "team_member_removed")
+	}
 	AuditLog(h.stores.Audit, c, "team.remove_member", "team", getTeamID(c), map[string]interface{}{
 		"member_id": memberID,
 	})
@@ -467,9 +497,39 @@ func (h *TeamHandler) UpdateRoles(c *gin.Context) {
 	}
 
 	c.JSON(http.StatusOK, gin.H{"data": roles})
+	// Notify all team members — role definitions changed
+	h.notifyTeamMembers(c.Request.Context(), teamID, "team_roles_updated")
 	AuditLog(h.stores.Audit, c, "team.update_roles", "team", teamID, map[string]interface{}{"roles": roles})
 }
 
+// memberUserID looks up the user_id for a team member by row ID.
+func (h *TeamHandler) memberUserID(ctx context.Context, teamID, memberID string) string {
+	members, err := h.stores.Teams.ListMembers(ctx, teamID)
+	if err != nil {
+		return ""
+	}
+	for _, m := range members {
+		if m.ID == memberID {
+			return m.UserID
+		}
+	}
+	return ""
+}
+
+// notifyTeamMembers sends an auth.changed event to all members of a team.
+func (h *TeamHandler) notifyTeamMembers(ctx context.Context, teamID, reason string) {
+	if h.hub == nil {
+		return
+	}
+	members, err := h.stores.Teams.ListMembers(ctx, teamID)
+	if err != nil {
+		return
+	}
+	for _, m := range members {
+		h.notifyAuthChanged(m.UserID, reason)
+	}
+}
+
 // getTeamRoles reads the roles array from team settings, falling back to builtins.
 func getTeamRoles(ctx context.Context, stores store.Stores, teamID string) []string {
 	team, err := stores.Teams.GetByID(ctx, teamID)

server/main.go

@@ -588,10 +588,12 @@ func main() {
 
 			// Teams (user: my teams)
 			teams := handlers.NewTeamHandler(stores, keyResolver)
+			teams.SetHub(hub)
 			protected.GET("/teams/mine", teams.MyTeams)
 
 			// Groups (user: my groups
 			groupH := handlers.NewGroupHandler(stores)
+			groupH.SetHub(hub)
 			protected.GET("/groups/mine", groupH.MyGroups)
 
 			// Team admin self-service
@@ -710,6 +712,7 @@ func main() {
 
 			// Teams (admin)
 			teamAdm := handlers.NewTeamHandler(stores, keyResolver)
+			teamAdm.SetHub(hub)
 			admin.GET("/teams", teamAdm.ListTeams)
 			admin.POST("/teams", teamAdm.CreateTeam)
 			admin.GET("/teams/:id", teamAdm.GetTeam)
@@ -730,6 +733,7 @@ func main() {
 
 			// Groups (admin
 			groupAdm := handlers.NewGroupHandler(stores)
+			groupAdm.SetHub(hub)
 			admin.GET("/groups", groupAdm.ListGroups)
 			admin.POST("/groups", groupAdm.CreateGroup)
 			admin.GET("/groups/:id", groupAdm.GetGroup)
@@ -789,6 +793,7 @@ func main() {
 			pkgAdm := handlers.NewPackageHandler(stores, packagesDir)
 			pkgAdm.SetSandbox(sandbox.New(sandbox.DefaultConfig()))
 			pkgAdm.SetBundledDir(cfg.BundledPackagesDir)
+			pkgAdm.SetHub(hub)
 
 			// Package registry — must be registered before /packages/:id
 			registryH := handlers.NewRegistryHandler(stores, packagesDir, pkgAdm)

server/pages/templates/base.html

@@ -75,12 +75,16 @@
     {{end}}
 
     {{if .Message.Visible}}
-    <div class="sw-shell__announcement" id="shellMessage">
+    <div class="sw-shell__announcement" id="shellMessage" data-msg-text="{{.Message.Text}}">
         <div class="sw-shell__announcement-inner sw-shell__announcement--{{.Message.Variant}}">
             <span class="sw-shell__announcement-text">{{.Message.Text}}</span>
-            <button class="sw-shell__banner-close" onclick="this.closest('.sw-shell__announcement').remove()" aria-label="Dismiss">&times;</button>
+            <button class="sw-shell__banner-close" aria-label="Dismiss"
+                    onclick="var el=this.closest('.sw-shell__announcement');var t=el.dataset.msgText||'';var k='armature_dismissed_'+Array.from(t).reduce(function(h,c){return((h<<5)-h)+c.charCodeAt(0)|0;},0);localStorage.setItem(k,'1');el.remove();">&times;</button>
         </div>
     </div>
+    <script nonce="{{.CSPNonce}}">
+    (function(){var el=document.getElementById('shellMessage');if(!el)return;var t=el.dataset.msgText||'';var k='armature_dismissed_'+Array.from(t).reduce(function(h,c){return((h<<5)-h)+c.charCodeAt(0)|0;},0);if(localStorage.getItem(k))el.remove();})();
+    </script>
     {{end}}
 
     <div class="surface" id="surface">

server/pages/templates/surfaces/admin.html

@@ -5,6 +5,7 @@
 */}}
 
 {{define "surface-admin"}}
+<div id="shell-topbar"></div>
 <div id="admin-mount" class="surface-admin" style="flex-direction:column;">
     {{/* Preact renders into this div. Show a loading state until it mounts. */}}
     <div class="settings-placeholder" style="padding:40px;text-align:center;">Loading admin&hellip;</div>

server/pages/templates/surfaces/docs.html

@@ -4,6 +4,7 @@
 */}}
 
 {{define "surface-docs"}}
+<div id="shell-topbar"></div>
 <div id="docs-mount" class="surface-docs">
     <div style="padding:40px;text-align:center;color:var(--text-3);">Loading docs&hellip;</div>
 </div>

server/pages/templates/surfaces/extension.html

@@ -13,6 +13,7 @@
 {{define "surface-extension"}}
 <div id="extension-surface" class="extension-surface"
      data-surface-id="{{.Surface}}">
+    <div id="shell-topbar"></div>
     <div id="extension-mount" class="extension-mount" data-ext="{{.Surface}}"></div>
 </div>
 {{end}}

server/pages/templates/surfaces/settings.html

@@ -4,6 +4,7 @@
 */}}
 
 {{define "surface-settings"}}
+<div id="shell-topbar"></div>
 <div id="settings-mount" class="surface-settings" style="flex-direction:column;">
     {{/* Preact renders into this div. Show a loading state until it mounts. */}}
     <div class="settings-placeholder" style="padding:40px;text-align:center;">Loading settings&hellip;</div>

server/pages/templates/surfaces/team-admin.html

@@ -5,6 +5,7 @@
 */}}
 
 {{define "surface-team-admin"}}
+<div id="shell-topbar"></div>
 <div id="team-admin-mount" class="surface-team-admin" style="height:100%;overflow:hidden;">
     <div class="settings-placeholder" style="padding:40px;text-align:center;">Loading team admin&hellip;</div>
 </div>