feat(updates): surface held packages distinctly with hold/unhold actions

Before this change, the OS Updates grid lumped held packages in with
the regular Updates list. Held entries — packages an operator has
explicitly pinned via apt-mark/dpkg — still appear in
`apt list --upgradable` when a newer version exists in the repos, but
apt will never upgrade them. Showing them in the active updates view
was misleading: "Update All" would silently skip them, the Security
count over-counted, and there was no UI to undo a hold from this page.

This change does four things across the agent, dashboard, and UI:

1. Agent — `Package` struct gains `IsHeld bool` with json tag
   `is_held,omitempty`. `aptPackageManager.ListUpgradable` now calls
   `apt-mark showhold` after parsing `apt list --upgradable` and marks
   each matching package. Failures from apt-mark are non-fatal; the
   listing falls back to IsHeld=false rather than erroring the whole
   request, because the hold lookup is purely an enrichment step.
   The pure-logic core (`applyHeldMarks`) is extracted so it can be
   unit-tested without execing.

2. Dashboard — mirroring agent struct; `agent.Package` gains the same
   `IsHeld` / `is_held` field so JSON round-trips intact.

3. UI — the pkg-view-filter dropdown gains a `Held` option between
   `Updates` and `All Packages`. The `Updates` filter is now
   `update_available=true AND is_held=false` (held rows belong in
   their own tab, not the active-upgrades plan); the `Held` filter
   shows only `is_held=true`. `Update All (N)` and the Security
   button counts also exclude held packages so what's shown matches
   what `apt upgrade` would actually do.

4. UI actions — a new `Hold` button mirrors the existing `Unhold`
   button; both POST to the matching `/api/os-updates/packages/{hold,
   unhold}` endpoints (which already existed). After a hold or unhold
   the row is updated in place and the active filter is reapplied so
   the row moves between the Updates and Held tabs without a refresh.

Tests:

- `TestApplyHeldMarks` covers the enrichment helper: held rows are
  marked, non-held rows are left alone, empty inputs are safe, and
  held names with no matching package are ignored.

Refs #45

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sarg3nt

gearbox-agent/internal/gears/updates/pm_apt.go

@@ -85,9 +85,47 @@ func (a *aptPackageManager) ListUpgradable() ([]Package, error) {
 	}
 	packages := a.parseAptListOutput(string(output))
 	a.fetchPackageSizes(packages)
+	a.markHeldPackages(packages)
 	return packages, nil
 }
 
+// markHeldPackages sets pkg.IsHeld=true for any package whose name appears in
+// `apt-mark showhold`. Held packages can still show up in `apt list --upgradable`
+// when a newer version exists in the repos; apt simply refuses to upgrade them.
+// Marking them lets the dashboard render a "held" badge and route the row to a
+// separate "Held" view instead of the active updates list.
+//
+// Errors from apt-mark are non-fatal: we just leave IsHeld=false rather than
+// failing the whole upgradable listing, since the held lookup is purely an
+// enrichment step.
+func (a *aptPackageManager) markHeldPackages(packages []Package) {
+	if len(packages) == 0 {
+		return
+	}
+	held, err := a.ListHeldPackages()
+	if err != nil {
+		return
+	}
+	applyHeldMarks(packages, held)
+}
+
+// applyHeldMarks is the pure-logic core of markHeldPackages, broken out so it
+// can be unit-tested without execing apt-mark.
+func applyHeldMarks(packages []Package, held []string) {
+	if len(held) == 0 {
+		return
+	}
+	heldSet := make(map[string]struct{}, len(held))
+	for _, name := range held {
+		heldSet[name] = struct{}{}
+	}
+	for i := range packages {
+		if _, ok := heldSet[packages[i].Name]; ok {
+			packages[i].IsHeld = true
+		}
+	}
+}
+
 func (a *aptPackageManager) TriggerUpdateCheck() error {
 	_, err := a.collector.runCommandWithOutput("apt-get", "update")
 	if err != nil {

gearbox-agent/internal/gears/updates/updates.go

@@ -38,7 +38,8 @@ type Package struct {
 	AvailableVersion string `json:"available_version"`
 	Architecture     string `json:"architecture"`
 	IsSecurityUpdate bool   `json:"is_security_update"`
-	Priority         string `json:"priority"` // low, medium, high, critical
+	IsHeld           bool   `json:"is_held,omitempty"` // Package is held (pinned via apt-mark/dpkg) — apt will not upgrade it even though a newer version is available
+	Priority         string `json:"priority"`          // low, medium, high, critical
 	Repository       string `json:"repository"`
 	Size             int64  `json:"size_bytes"`    // Download size in bytes
 	ChangelogURL     string `json:"changelog_url"` // URL to package changelog (Launchpad)

gearbox-agent/internal/gears/updates/updates_test.go

@@ -480,3 +480,49 @@ func TestAptSnapshot_Fields(t *testing.T) {
 		t.Error("CreatedAt mismatch")
 	}
 }
+
+// TestApplyHeldMarks verifies that the held-marker correctly flips IsHeld on
+// packages whose names appear in the held list, leaves others alone, and is a
+// no-op when there are no held packages or no packages.
+func TestApplyHeldMarks(t *testing.T) {
+	t.Run("marks held packages and leaves others alone", func(t *testing.T) {
+		pkgs := []Package{
+			{Name: "openssl"},
+			{Name: "linux-image-generic"},
+			{Name: "nginx"},
+		}
+		applyHeldMarks(pkgs, []string{"openssl", "nginx"})
+
+		if !pkgs[0].IsHeld {
+			t.Errorf("openssl should be held")
+		}
+		if pkgs[1].IsHeld {
+			t.Errorf("linux-image-generic should not be held")
+		}
+		if !pkgs[2].IsHeld {
+			t.Errorf("nginx should be held")
+		}
+	})
+
+	t.Run("empty held list is a no-op", func(t *testing.T) {
+		pkgs := []Package{{Name: "openssl"}}
+		applyHeldMarks(pkgs, nil)
+		if pkgs[0].IsHeld {
+			t.Errorf("no packages should be marked when held list is empty")
+		}
+	})
+
+	t.Run("empty packages list is safe", func(t *testing.T) {
+		// Must not panic.
+		applyHeldMarks(nil, []string{"openssl"})
+		applyHeldMarks([]Package{}, []string{"openssl"})
+	})
+
+	t.Run("held name with no matching package is ignored", func(t *testing.T) {
+		pkgs := []Package{{Name: "nginx"}}
+		applyHeldMarks(pkgs, []string{"ghost-package", "nginx"})
+		if !pkgs[0].IsHeld {
+			t.Errorf("nginx should be held")
+		}
+	})
+}

gearbox/internal/framework/agent/models.go

@@ -666,6 +666,7 @@ type Package struct {
 	AvailableVersion string `json:"available_version"`
 	Architecture     string `json:"architecture"`
 	IsSecurityUpdate bool   `json:"is_security_update"`
+	IsHeld           bool   `json:"is_held,omitempty"` // Held packages (apt-mark/dpkg pinned) won't be upgraded even when a newer version is available.
 	Priority         string `json:"priority"`
 	Repository       string `json:"repository"`
 	Size             int64  `json:"size_bytes"`

gearbox/internal/framework/templates/pages/os_updates.templ

@@ -223,6 +223,7 @@ templ OSUpdatesPage(data OSUpdatesPageData) {
 									class="h-[38px] px-3 py-1.5 text-sm border border-gray-300 dark:border-slate-600 rounded-lg bg-white dark:bg-slate-800 text-gray-700 dark:text-gray-300 focus:outline-none focus:ring-2 focus:ring-blue-500"
 								>
 									<option value="updates">Updates</option>
+									<option value="held">Held</option>
 									<option value="all">All Packages</option>
 								</select>
 								if data.CanAction {

gearbox/static/js/os-updates/os-updates-page.js

@@ -2055,6 +2055,9 @@ let allPackagesLoaded = false;
 
 // Normalize upgradable Package objects (from /api/os-updates/packages) to the
 // shape expected by the grid (which was designed around InstalledPackage).
+// is_held flows from the agent; held packages can still appear in
+// `apt list --upgradable` when a newer version exists but apt-mark/dpkg has
+// pinned them. The UI surfaces them via a "held" badge and a dedicated tab.
 function normalizeUpgradablePackages(packages) {
 	return packages.map(p => ({
 		name: p.name,
@@ -2064,7 +2067,7 @@ function normalizeUpgradablePackages(packages) {
 		description: '',
 		update_available: true,
 		is_security_update: p.is_security_update || false,
-		is_held: false,
+		is_held: p.is_held || false,
 		package_url: p.package_url || '',
 	}));
 }
@@ -2214,13 +2217,21 @@ function initInstalledPackagesGrid(el, packages, canAction) {
 			title: '',
 			field: 'name',
 			headerSort: false,
-			width: 220,
+			width: 260,
 			hozAlign: 'right',
 			formatter: function(cell) {
 				const row = cell.getRow().getData();
-				const holdBtn = row.is_held
-					? '<button class="pkg-unhold-btn px-2.5 py-1 text-xs bg-yellow-100 dark:bg-yellow-900/30 hover:bg-yellow-200 dark:hover:bg-yellow-900/50 text-yellow-700 dark:text-yellow-400 rounded transition-colors mr-1">Unhold</button>'
-					: '';
+				// Show Unhold for held packages, Hold for any upgradable-but-not-held
+				// row. The action mirrors the existing Unhold pattern and posts to
+				// the matching /api/os-updates/packages/hold endpoint.
+				let holdBtn;
+				if (row.is_held) {
+					holdBtn = '<button class="pkg-unhold-btn px-2.5 py-1 text-xs bg-yellow-100 dark:bg-yellow-900/30 hover:bg-yellow-200 dark:hover:bg-yellow-900/50 text-yellow-700 dark:text-yellow-400 rounded transition-colors mr-1">Unhold</button>';
+				} else if (row.update_available) {
+					holdBtn = '<button class="pkg-hold-btn px-2.5 py-1 text-xs bg-yellow-50 dark:bg-yellow-900/20 hover:bg-yellow-100 dark:hover:bg-yellow-900/40 text-yellow-700 dark:text-yellow-400 rounded transition-colors mr-1">Hold</button>';
+				} else {
+					holdBtn = '';
+				}
 				return holdBtn + '<button class="pkg-remove-btn px-2.5 py-1 text-xs bg-red-100 dark:bg-red-900/30 hover:bg-red-200 dark:hover:bg-red-900/50 text-red-700 dark:text-red-400 rounded transition-colors">Remove</button>';
 			},
 			cellClick: function(e, cell) {
@@ -2229,6 +2240,8 @@ function initInstalledPackagesGrid(el, packages, canAction) {
 					removeInstalledPackageTabulator(cell, name);
 				} else if (e.target.classList.contains('pkg-unhold-btn')) {
 					unholdPackage(name, cell);
+				} else if (e.target.classList.contains('pkg-hold-btn')) {
+					holdPackage(name, cell);
 				}
 			}
 		});
@@ -2271,14 +2284,23 @@ function _applyPkgViewFilter(value, allData) {
 	if (!installedPkgTable) return;
 
 	if (value === 'updates') {
-		installedPkgTable.setFilter('update_available', '=', true);
+		// Active updates: upgradable AND not held. "Hold" is an explicit operator
+		// opt-out from upgrade, so held rows do not belong in the updates view.
+		installedPkgTable.setFilter([
+			{ field: 'update_available', type: '=', value: true },
+			{ field: 'is_held', type: '=', value: false },
+		]);
+	} else if (value === 'held') {
+		installedPkgTable.setFilter('is_held', '=', true);
 	} else {
 		installedPkgTable.clearFilter();
 	}
 
-	// Count packages with updates
-	const updateCount = allData.filter(p => p.update_available).length;
-	const securityCount = allData.filter(p => p.is_security_update).length;
+	// Count packages excluding held ones — held packages are intentionally
+	// excluded from the upgrade plan, so "Update All (N)" should reflect only
+	// what would actually be upgraded.
+	const updateCount = allData.filter(p => p.update_available && !p.is_held).length;
+	const securityCount = allData.filter(p => p.is_security_update && !p.is_held).length;
 
 	// Show/hide Update All button
 	const updateAllBtn = document.getElementById('pkg-update-all-btn');
@@ -2362,6 +2384,44 @@ function removeInstalledPackageTabulator(cell, name) {
 
 // ── Package Hold / Unhold ─────────────────────────────────────────────────────
 
+async function holdPackage(name, cell) {
+	showConfirmModal({
+		title: 'Hold Package',
+		message: 'Hold ' + name + '? This prevents apt from upgrading it until the hold is removed.',
+		type: 'warning',
+		confirmText: 'Hold',
+		onConfirm: async () => {
+			try {
+				const resp = await fetch('/api/os-updates/packages/hold?server=' + currentServerID, {
+					method: 'POST',
+					headers: { 'Content-Type': 'application/json' },
+					body: JSON.stringify({ name: name })
+				});
+				if (!resp.ok) {
+					const errMsg = await extractErrorMessage(resp);
+					throw new Error(errMsg);
+				}
+				showToast(name + ' is now held', 'success');
+				// Flip is_held in place so the row re-renders into the held filter.
+				if (cell) {
+					const row = cell.getRow();
+					const data = row.getData();
+					data.is_held = true;
+					row.update(data);
+					// Re-apply the active filter so the row moves between tabs
+					// without requiring a manual switch.
+					const filterSelect = document.getElementById('pkg-view-filter');
+					if (filterSelect) {
+						_applyPkgViewFilter(filterSelect.value, installedPkgTable.getData());
+					}
+				}
+			} catch (err) {
+				showToast('Failed to hold package: ' + err.message, 'error');
+			}
+		}
+	});
+}
+
 async function unholdPackage(name, cell) {
 	showConfirmModal({
 		title: 'Remove Hold',
@@ -2380,12 +2440,17 @@ async function unholdPackage(name, cell) {
 					throw new Error(errMsg);
 				}
 				showToast(name + ' hold removed', 'success');
-				// Update the row data in-place
+				// Update the row data in-place and reapply the active filter so
+				// the row moves out of the "Held" tab when viewing it.
 				if (cell) {
 					const row = cell.getRow();
 					const data = row.getData();
 					data.is_held = false;
 					row.update(data);
+					const filterSelect = document.getElementById('pkg-view-filter');
+					if (filterSelect) {
+						_applyPkgViewFilter(filterSelect.value, installedPkgTable.getData());
+					}
 				}
 			} catch (err) {
 				showToast('Failed to remove hold: ' + err.message, 'error');