Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Keep v6 migration on preserved-state upgrade paths

pulse-triage[bot]99f72ffedb1e
diff --git a/docs/UPGRADE_v6.md b/docs/UPGRADE_v6.md
index 3a244366ab..345132f806 100644
--- a/docs/UPGRADE_v6.md
+++ b/docs/UPGRADE_v6.md
@@ -1,6 +1,11 @@
# Upgrade to Pulse v6
-This guide covers practical upgrade steps for existing Pulse installs moving to v6.
+This guide covers the v5-to-v6 migration and its compatibility changes. For
+updates within v6, use [Updating Pulse](AUTO_UPDATE.md); the historical packets
+below are context, not an instruction to install an old version or downgrade.
+Choose an actually [published software release](https://github.com/rcourtman/Pulse/releases),
+not a draft, source tag or Helm-chart asset. Keep the existing runtime edition:
+public Community downloads do not replace a private Pro build.
For the current v6 beta packet, see:
@@ -135,69 +140,126 @@ For earlier stable v6 packets and rollout references, see:
- `docs/releases/V6_CHANGELOG.md`
The published GitHub release is the authority for what users can install as
-stable. Keep v5.1.35 as the explicit rollback target for the v6.0.0 cutover.
+stable. The v6.0.0 cutover recorded v5.1.35 as its rollback target; that
+historical choice is not a safe downgrade procedure for a current installation.
## Before You Upgrade
-- Create an encrypted config backup: **Settings → System → Recovery → Create Backup** (older versions labeled this **Backups**)
-- Open **Settings → System → Updates** and review the upgrade checks on the update plan. Pulse checks the server update path, current agent continuity, and agent reporting token scope before you install. These checks describe the currently reported fleet; they do not prove every installed agent is online or already updated.
-- Confirm you can access the host/container console (for rollback and bootstrap token retrieval)
-- If the instance uses SSO without a configured local administrator, map a trusted IdP group to the built-in `admin` role before upgrading. SSO authentication alone does not grant instance-administrator access; an unmapped, `operator`, or `viewer` SSO session cannot manage settings, transfer configuration, or control infrastructure actions.
-- If you have any external integrations or scripts: review the **API Changes** section below
+- Keep a private, consistent backup of the existing installation's active data,
+ matching encryption/signing keys and deployment configuration. **Create Backup**
+ in **Settings → System → Recovery** (older versions labelled this **Backups**)
+ is a configuration export, **not a full-state backup**: history and agent
+ enrolment state are excluded. Follow [full-state recovery](MIGRATION.md#full-state-recovery);
+ do not copy live data or assume an updater snapshot includes every active store.
+- Confirm existing administrator access to Pulse and its host/container console.
+ Preserve credentials, connection state, agent identities and the existing
+ service and data/config paths. An upgrade does not require first-time setup.
+- Choose a maintenance window: updates interrupt monitoring and alert delivery.
+ Arrange independent coverage. Do not update during a backup, freeze/thaw or
+ an unresponsive-workload incident; use the [backup safety precaution](VM_DISK_MONITORING.md#backup-safety)
+ before restoring paused monitoring.
+- Open **Settings → System → Updates** and review the upgrade checks on the
+ update plan. These describe the currently reported fleet and server update
+ path, not every installed agent's continuity or convergence.
+- If the instance uses SSO without a configured local administrator, verify the
+ trusted IdP group's existing built-in `admin` mapping before upgrading. SSO
+ authentication alone does not grant instance-administrator access; an unmapped,
+ `operator` or `viewer` SSO session cannot manage settings or transfer configuration.
+ Do not remove role gating to repair a denial.
+- Review [API changes](#api-changes) for existing integrations and
+ [paid licensing connectivity](#breaking-change-paid-licensing-requires-connectivity)
+ before changing a paid installation. Preserve the private Pro runtime.
## Upgrade Paths
### systemd and Proxmox LXC installs
-Preferred path:
-
-- **Settings → System → Updates**
-
-If you prefer CLI, use this command only when `/bin/update` was installed by
-the Pulse server installer:
-
-```bash
-sudo /bin/update --version vX.Y.Z
-```
-
-On Proxmox community-scripts containers, `/bin/update` can belong to the
-community-scripts updater, which can ignore `--version`. If that is your
-installation, the helper is absent, or you cannot confirm its owner, follow the
-[signed server-installer flow](INSTALL.md#2-bare-metal--systemd) and set
-`PULSE_VERSION` to the exact target tag. This also applies to rollback. Verify
-the installed version with `GET /api/version` after the service restarts.
-
-Agent updates and v5-to-v6 agent upgrades use the `/install.sh` command generated
-in **Settings → Infrastructure → Install on a host**. That screen is for both
-first installs and in-place agent upgrades.
-
-Operator note for builds after `v6.0.0-rc.2`: the historical Pulse update
-signer was not recovered. Hosts pinned to the `rc.2` trust root should not
-assume unattended continuity into newer prerelease or GA artifacts; plan a
-manual reinstall or other explicit trust migration before testing those builds.
+Use **Settings → System → Updates** where supported. For CLI updates, follow
+[the existing-installation manual update procedure](INSTALL.md#manual-update):
+it checks the helper's ownership and preserves the existing service and
+data/config paths. Work inside the existing Pulse LXC, not on the Proxmox host
+or a monitored guest. Do not execute an absent or unknown helper; its filename
+`/bin/update` alone does not identify its owner or prove it accepts an exact version.
+Do not apply default installation paths over a custom deployment.
+
+If a community helper selects a Helm-chart asset, use
+[chart-selection recovery](AUTO_UPDATE.md#a-helper-selects-a-helm-chart-release),
+not another blind attempt, a GitHub token or a recreated LXC. The public signed
+server-installer flow is for Community; do not replace a private Pro runtime
+with it. Preserve the running version, edition and service health first.
+
+Agent updates and v5-to-v6 agent upgrades are separate from server updates.
+Use the [trusted-instance agent procedure](UNIFIED_AGENT.md#private-file-installation-linux-macos-and-nas)
+and **Settings → Infrastructure → Install on a host** for first installs and
+in-place agent upgrades; do not use the GitHub server installer for `pulse-agent`.
+
+For hosts pinned to `v6.0.0-rc.2`, the historical Pulse update signer was not
+recovered. This records a trust-continuity limit, not an instruction to reinstall
+or bypass signature verification. Arrange an explicit verified trust migration
+through the deployment's recovery procedure, preserving its identity, data and
+private edition; do not assume unattended continuity from that early trust root.
### Docker
-```bash
-docker pull rcourtman/pulse:vX.Y.Z
-docker compose up -d
-```
+Follow [Docker server updates](DOCKER.md#-updates) for the existing deployment.
+Change the configured image to the exact published tag first, then pull and
+recreate only the Pulse service, preserving mounted data, credentials and
+collector settings. Pulling a different tag does not change a hardcoded Compose
+image or the running container. Keep a private Pro image private; do not replace
+it with `rcourtman/pulse`. Do not run `docker compose down`, remove volumes or
+recreate unrelated services for a Pulse-only update.
### Kubernetes (Helm)
-```bash
-helm repo update
-helm upgrade pulse pulse/pulse -n pulse
-```
+Follow [the Helm deployment guidance](KUBERNETES.md#1-deploying-the-pulse-server),
+preserving the existing release, namespace, values and persistent volumes.
+Select the intended published chart and server image separately; a chart version
+alone does not establish the running server version or edition. Keep existing
+private Pro image configuration and Secret references; do not paste credentials
+into Helm command arguments or share resolved values or Secret YAML.
## Post-Upgrade Checklist
-- Confirm version: `GET /api/version`
-- Confirm scheduler health: `GET /api/monitoring/scheduler/health`
-- Confirm unified resources API is responding: `GET /api/resources`
-- Confirm nodes are polling and no breakers are stuck open
-- Confirm notifications still send (send a test)
-- Confirm agents are connected (if used)
+Use existing authenticated browser/API access and passive observations, not
+new diagnostic traffic or active probes just to fill this checklist. For API reads use an [authenticated browser or private
+header file](API.md#-authentication), never a token or session cookie in a
+command, URL or report.
+
+- Confirm the **running server version and edition**, not just the selected
+ release or a completed download. `GET /api/version` reports the server version;
+ a valid signature is not completed installation or healthy operation.
+- Observe ordinary polling, current readings and their original source/time.
+ A green connection badge or response from `/api/health` does not prove every
+ collector recovered. Read-only `GET /api/monitoring/scheduler/health` and
+ `GET /api/resources` can supplement, not replace, those observations.
+- Check ordinary notification delivery already observed and its destination/
+ resource identity. A successful Test does not prove ordinary delivery; do not
+ send a Test, trigger an alert or replay a queue just to complete this checklist.
+- Check agents individually where used. A current server does not prove that
+ every installed agent upgraded, authenticated or resumed reporting.
+- If monitoring was paused for backup safety, restore only its previously active
+ services/timers after independent thaw, every-covered-filesystem writes and
+ workload liveness checks pass. An OK backup task is not that proof.
+
+### Failed or interrupted upgrade
+
+Check the running version, edition and service health before another attempt.
+Keep the original attempt time/timezone, error and any already available updater
+or host stop evidence privately. A broken pipe does not establish why a service
+or its whole LXC stopped; a later boot is a new run, not the stop's cause.
+
+Use [update failure checks](AUTO_UPDATE.md#update-failed) and, if needed,
+[timer-only containment](AUTO_UPDATE.md#pause-further-unattended-attempts-without-stopping-pulse)
+without stopping a working Pulse server. Do not start, cancel or repeat an
+uncertain in-progress updater. Do not repeat the update, reboot, restore, run
+Diagnostics or delete rollback backups merely to obtain evidence.
+
+An older binary may not understand newer data. Use the
+[stopped-service recovery procedure](AUTO_UPDATE.md#manual-rollback) for matching
+data and keys, preserving reversible copies of the failed state. An image or
+binary change alone is not a data rollback. Share only relevant locally reviewed,
+redacted observations via [Getting Help](TROUBLESHOOTING.md#-getting-help), not
+backups, full logs or deployment configuration.
## v5 to v6 Operator FAQ
@@ -287,33 +349,27 @@ older v5 agents do not understand observer configuration.
### Can I keep Pulse v5 stable while I test Pulse v6?
-Yes. Keep a rollback path available while you evaluate v6. The final release
-on the v5 line is 5.1.36. On installations with the Pulse-owned update helper,
-the rollback command is:
-
-```bash
-sudo /bin/update --version v5.1.36
-```
+Keep the original installation and a verified recovery backup. Evaluate a
+restored copy only in an [isolated recovery instance](AUTO_UPDATE.md#manual-rollback)
+with no access to monitored systems or notification destinations; do not start
+a second connected copy. Moving the binary back does not reverse data migrated
+by v6. The final v5 release, v5.1.36, is end-of-life; it is historical context,
+not a supported recovery target for every current installation.
-The [installer ownership requirements](#systemd-and-proxmox-lxc-installs) above
-also apply to this command.
+Returning to an earlier version requires a deployment-specific recovery plan,
+matching data and keys, a compatible binary and the same edition. Follow the
+[rollback limits](INSTALL.md#rollback), not a generic `/bin/update` downgrade
+against the live migrated data.
### Why did my v5 install upgrade itself to v6?
-Pulse 5.1.29 and later pin the built-in updater to the 5.1.x line and never
-offer v6, so upgrading from those versions is always a manual step. Pulse
-5.1.28 and older have no such pin: installs with auto-update enabled follow
-the newest stable GitHub release, which is now v6. If that happened to you,
-your data and configuration carry over; run through the Post-Upgrade
-Checklist above to confirm everything still works. To return to v5 with the
-Pulse-owned update helper, run:
-
-```bash
-sudo /bin/update --version v5.1.36
-```
-
-For community-scripts installations or an unknown helper owner, use the
-[installer ownership guidance](#systemd-and-proxmox-lxc-installs) above.
+Pulse 5.1.29 and later pin the built-in updater to the 5.1.x line. Pulse 5.1.28
+and older have no such pin: an enabled updater can follow a newer stable release.
+This version-selection behaviour does not prove that the resulting upgrade or
+all collectors recovered. Check the running version and edition using the
+[post-upgrade checklist](#post-upgrade-checklist); preserve the original state
+and [recovery evidence](#failed-or-interrupted-upgrade) if anything remains wrong.
+Do not blindly run another updater or downgrade just because the target changed.
## Migration Notes (v6)
@@ -364,9 +420,10 @@ Pulse v6 feature gating is driven by the entitlements endpoint:
- `GET /api/license/entitlements`
For self-hosted v6, Pulse no longer sells monitored-system volume. Core
-monitoring stays available across Community, Relay, and Pro, while Relay and
-Pro sell convenience, history, AI operations, and advanced administration.
-Relay raises history to 14 days, while Pro raises it to 90 days.
+monitoring stays available across Community and Pro. Relay is no longer sold;
+existing Relay subscribers receive Pro features at their current price while
+their subscription continues. Preserve those entitlements and the private
+runtime when upgrading; see [current plans](PULSE_PRO.md).
Self-hosted v6 does not expose a general in-app trial, trial-return callback,
or hosted AI quickstart path. Ordinary upgraded self-hosted installs should use
@@ -449,7 +506,7 @@ When an existing paid user asks what changes for them specifically, use this rul
- Existing lifetime customers remain permanently valid, with self-hosted monitoring and child-resource volume not metered under the current v6 policy.
- Legacy paid v5 licenses migrated into v6 outside the recurring grandfathered path can still exchange into the v6 activation model without repurchasing. Migration records can preserve the original cohort for support and audit, but self-hosted monitoring volume is no longer the paid gate.
- Former recurring customers who already canceled, or who cancel and later return, do not resume the old grandfathered pricing automatically; they re-enter on current public v6 pricing for paid features while self-hosted monitoring remains included without a monitored-system volume gate.
-- New self-hosted v6 purchases use the current Community / Relay / Pro plan model with core monitoring included.
+- New self-hosted v6 purchases use the current Community / Pro plan model with core monitoring included; Relay is no longer sold.
If a self-hosted v6 install sees a new monitored-system, guest, or child-resource volume cap after moving to v6, treat that as a regression, not as expected upgrade behavior.
@@ -476,13 +533,13 @@ The migrations are additive:
- action audit records preserve execution and verification as separate truth.
Supported legacy JSON fields remain readable where older clients need them,
-but the primary v6 runtime has one writable owner for each domain. Pulse Mobile
-now reads the canonical Patrol attention queue. Operators should upgrade
-desktop and mobile clients together when they depend on acknowledgement,
-evidence, protection, or action-verification parity.
+but the primary v6 runtime has one writable owner for each domain. Server and
+agent/client versions remain separate; a server upgrade does not establish
+client convergence or every consuming surface's recovery.
-Before the upgrade, back up the Pulse data directory and confirm the service
-account can write the alert, notification, recovery, and action stores. After
+Before the upgrade, keep the consistent [full-state backup](MIGRATION.md#full-state-recovery)
+and confirm the existing service account can write the active stores without
+widening its permissions just to diagnose a failure. After
startup, verify that the Patrol navigation count matches the active queue,
inspect one evidence/protection drill-down, and confirm stale collection does
not appear resolved. Pulse Pro users should also verify entitlement
diff --git a/docs/release-control/v6/internal/subsystems/deployment-installability.md b/docs/release-control/v6/internal/subsystems/deployment-installability.md
index d395b39cce..5057eedde5 100644
--- a/docs/release-control/v6/internal/subsystems/deployment-installability.md
+++ b/docs/release-control/v6/internal/subsystems/deployment-installability.md
@@ -8164,3 +8164,40 @@ nonzero exit. `TestProviderMSPStartupCommandSeparatesDiagnostics` checks three
consumer shapes with controlled successful stderr; it is not Docker acceptance.
Hosted mounted-secret/readiness/persistence/refusal/cleanup checks remain required.
Frontend fixture reformatting retains all assertions and changes no runtime UI.
+
+
+### Current v6 migration guidance: preserved-state upgrade and recovery
+
+The existing `docs/UPGRADE_v6.md` and byte-identical shipped guide are migration
+entry points, not independent generic update or downgrade recipes. Historical
+release and rollback packets remain historical; they grant no compatibility
+claim for an older binary against current migrated data. This active guidance
+supersedes the early-cutover shortcut wording above, not retained release facts.
+
+Preparation distinguishes a configuration export from a consistent full-state
+backup, with matching keys and deployment settings. Existing service/data paths,
+credentials, agent identity and runtime edition survive. The guide routes CLI,
+Docker and Helm users to existing deployment-owned procedures; it does not
+execute an unknown helper, recreate unrelated services, discard configured
+values/volumes or replace private Pro with public Community. Old signing-root
+continuity warnings retain verified trust migration without prescribing a
+reinstall or weakening signatures.
+
+Post-upgrade observations distinguish running version, edition, ordinary
+collector/notification recovery and agent convergence from download/signature
+success. They do not induce notifications or active diagnostic traffic. An
+uncertain attempt retains original stop evidence and backups, uses timer-only
+containment when appropriate, and restores matching data/keys only through the
+stopped-service recovery path. Historical v5 testing requires an isolated,
+disconnected recovery copy; a generic binary downgrade is not data rollback.
+Relay is not offered for new purchases; existing subscribers preserve their
+current-price Pro entitlements and private runtime while subscribed.
+
+Verification: `scripts/tests/test_upgrade_v6_docs.py` checks the complete
+preparation/routes/recovery/compatibility chain and actual local link targets;
+`release_promotion_policy_test.py` preserves the trust warning and current
+procedure routes without forcing the retired shortcuts. Consuming Docs/router
+browser proof at desktop and phone must inspect the rendered safety boundaries,
+keyboard/touch linked recovery navigation and direct/reload fragments. These
+are help qualification, not installed upgrade, native recovery, paid deployment
+or release acceptance.
diff --git a/frontend-modern/browser-tests/upgrade-guide-safety.cjs b/frontend-modern/browser-tests/upgrade-guide-safety.cjs
new file mode 100644
index 0000000000..72e9311076
--- /dev/null
+++ b/frontend-modern/browser-tests/upgrade-guide-safety.cjs
@@ -0,0 +1,130 @@
+// Consume the existing v6 migration entry point with the production Docs/router.
+// Safe static documentation and one synthetic security-status GET only.
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { chromium } = require('playwright');
+const hash = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+
+(async () => {
+ const root = path.resolve('frontend-modern');
+ const output = path.resolve('tmp/upgrade-guide-browser');
+ fs.mkdirSync(output, { recursive: true });
+ const source = fs.readFileSync(path.join(root, 'public/docs/UPGRADE_v6.md'));
+ assert.equal(hash(source), hash(fs.readFileSync(path.resolve('docs/UPGRADE_v6.md'))));
+ assert.equal(require('playwright/package.json').version,
+ JSON.parse(fs.readFileSync('tests/integration/package-lock.json')).packages['node_modules/@playwright/test'].version);
+ const port = 5263;
+ const origin = `http://127.0.0.1:${port}`;
+ process.chdir(root);
+ const { createServer } = await import(path.join(root, 'node_modules/vite/dist/node/index.js'));
+ const server = await createServer({ root, configFile: path.join(root, 'vite.config.ts'),
+ cacheDir: path.join(root, 'node_modules/.vite-upgrade-guide'),
+ server: { host: '127.0.0.1', port, strictPort: true },
+ optimizeDeps: { noDiscovery: true, include: [] } });
+ const result = { result: 'incomplete', playwright: require('playwright/package.json').version,
+ driver_sha256: hash(fs.readFileSync(__filename)), document_sha256: hash(source),
+ scope: 'Existing migration help and actual linked Docs consumers; not installed upgrade, native recovery or private runtime acceptance',
+ cases: [], cleanup: { browser: false, server: false } };
+ let browser;
+ try {
+ await server.listen();
+ for (const [width, tone] of [[1280, 'light'], [390, 'dark']]) {
+ const phone = width < 500;
+ browser = await chromium.launch({ headless: true, channel: 'chromium', args: ['--no-sandbox'] });
+ const context = await browser.newContext({ viewport: { width, height: 1000 },
+ ...(phone ? { isMobile: true, hasTouch: true } : {}), locale: 'en-GB' });
+ const page = await context.newPage();
+ page.setDefaultTimeout(15000);
+ const record = { width, tone, input: phone ? 'touch' : 'keyboard',
+ browserVersion: browser.version(), checks: [], captures: [], pageErrors: [], apiRequests: [],
+ externalRequests: [], servedGuide: [] };
+ result.cases.push(record);
+ page.on('pageerror', error => record.pageErrors.push(error.message));
+ page.on('console', message => { if (message.type() === 'error') record.pageErrors.push(message.text()); });
+ page.on('response', async response => {
+ if (new URL(response.url()).pathname === '/docs/UPGRADE_v6.md') {
+ record.servedGuide.push({ status: response.status(), sha256: hash(await response.body()) });
+ }
+ });
+ await page.route('**/*', route => {
+ const request = route.request(); const url = new URL(request.url());
+ if (url.origin !== origin) { record.externalRequests.push(url.href); return route.abort(); }
+ if (url.pathname.startsWith('/api/')) {
+ record.apiRequests.push({ method: request.method(), path: url.pathname });
+ if (request.method() !== 'GET' || url.pathname !== '/api/security/status') return route.abort();
+ return route.fulfill({ status: 200, contentType: 'application/json', body: '{}' });
+ }
+ return route.continue();
+ });
+ const activate = async locator => {
+ await locator.scrollIntoViewIfNeeded();
+ if (phone) await locator.tap();
+ else { await locator.focus(); await page.keyboard.press('Enter'); }
+ };
+ const overflow = async () => assert.ok(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth + 1));
+ const capture = async (id, name) => {
+ await page.evaluate(fragment => { window.location.hash = '#' + fragment; }, id);
+ await page.waitForFunction(fragment => document.activeElement?.id === fragment, id);
+ await overflow();
+ const filename = `chromium-${width}-${name}.png`;
+ await page.screenshot({ path: path.join(output, filename) });
+ record.captures.push(filename);
+ };
+ await page.goto(`${origin}/browser-tests/docs-fragment-navigation.html`, { waitUntil: 'domcontentloaded' });
+ await activate(page.getByRole('link', { name: '← All documentation', exact: true }));
+ await activate(page.locator('a[data-doc-link][href="/docs/UPGRADE_v6"]').first());
+ await page.getByRole('heading', { name: 'Upgrade to Pulse v6', exact: true }).waitFor();
+ if (tone === 'dark') await page.evaluate(() => document.documentElement.classList.add('dark'));
+ const article = page.locator('article');
+ let text = await article.innerText();
+ for (const boundary of ['not a full-state backup', 'history and agent enrolment state',
+ 'matching encryption/signing keys', 'recreate only the Pulse service',
+ 'Do not start, cancel or repeat', 'An image or binary change alone is not a data rollback',
+ 'Relay is no longer sold']) assert.ok(text.includes(boundary), boundary);
+ assert.equal(await article.locator('pre').filter({ hasText: '/bin/update --version' }).count(), 0);
+ assert.equal(await article.locator('pre').filter({ hasText: 'docker compose up' }).count(), 0);
+ record.checks.push('Published guide entry, full-state/edition/uncertainty boundaries, no copied downgrade/all-service shortcut');
+ await capture('before-you-upgrade', 'preparation');
+ await capture('docker', 'deployment');
+ // Real cross-document route and fragment focus, not an asserted href only.
+ for (const [href, id, phrase] of [
+ ['/docs/MIGRATION#full-state-recovery', 'full-state-recovery', 'configuration export'],
+ ['/docs/INSTALL#manual-update', 'manual-update', 'helper'],
+ ['/docs/DOCKER#-updates', '-updates', 'image'],
+ ['/docs/AUTO_UPDATE#manual-rollback', 'manual-rollback', 'keys'],
+ ]) {
+ await activate(page.locator(`a[data-doc-link][href="${href}"]`).first());
+ await page.waitForURL(`**${href}`);
+ await page.waitForFunction(fragment => document.activeElement?.id === fragment, id);
+ assert.ok((await page.locator('article').innerText()).toLowerCase().includes(phrase));
+ await overflow();
+ record.checks.push(`Consuming ${href}: input activation, focused heading and rendered recovery/deployment text`);
+ await page.goBack({ waitUntil: 'domcontentloaded' });
+ await page.getByRole('heading', { name: 'Upgrade to Pulse v6', exact: true }).waitFor();
+ }
+ await capture('failed-or-interrupted-upgrade', 'uncertainty');
+ await capture('can-i-keep-pulse-v5-stable-while-i-test-pulse-v6', 'rollback');
+ await page.evaluate(() => { window.location.hash = '#failed-or-interrupted-upgrade'; });
+ await page.waitForFunction(() => document.activeElement?.id === 'failed-or-interrupted-upgrade');
+ await page.reload({ waitUntil: 'domcontentloaded' });
+ await page.waitForFunction(() => document.activeElement?.id === 'failed-or-interrupted-upgrade');
+ assert.ok((await page.locator('article').innerText()).includes('Do not repeat the update'));
+ record.checks.push('Direct fragment and real reload retain focused interrupted-upgrade help');
+ assert.deepEqual(record.pageErrors, []);
+ assert.deepEqual(record.externalRequests, []);
+ assert.ok(record.apiRequests.every(request => request.method === 'GET' && request.path === '/api/security/status'));
+ assert.ok(record.servedGuide.length >= 1);
+ assert.ok(record.servedGuide.every(observation => observation.status === 200 && observation.sha256 === result.document_sha256));
+ await browser.close(); browser = undefined;
+ }
+ result.result = 'passed'; result.verifiedAt = new Date().toISOString();
+ } finally {
+ if (browser) await browser.close();
+ result.cleanup.browser = true;
+ await server.close(); result.cleanup.server = true;
+ fs.writeFileSync(path.join(output, 'result.json'), JSON.stringify(result, null, 2) + '\n');
+ console.log(JSON.stringify(result));
+ }
+})().catch(error => { console.error(error); process.exitCode = 1; });
diff --git a/frontend-modern/public/docs/UPGRADE_v6.md b/frontend-modern/public/docs/UPGRADE_v6.md
index 3a244366ab..345132f806 100644
--- a/frontend-modern/public/docs/UPGRADE_v6.md
+++ b/frontend-modern/public/docs/UPGRADE_v6.md
@@ -1,6 +1,11 @@
# Upgrade to Pulse v6
-This guide covers practical upgrade steps for existing Pulse installs moving to v6.
+This guide covers the v5-to-v6 migration and its compatibility changes. For
+updates within v6, use [Updating Pulse](AUTO_UPDATE.md); the historical packets
+below are context, not an instruction to install an old version or downgrade.
+Choose an actually [published software release](https://github.com/rcourtman/Pulse/releases),
+not a draft, source tag or Helm-chart asset. Keep the existing runtime edition:
+public Community downloads do not replace a private Pro build.
For the current v6 beta packet, see:
@@ -135,69 +140,126 @@ For earlier stable v6 packets and rollout references, see:
- `docs/releases/V6_CHANGELOG.md`
The published GitHub release is the authority for what users can install as
-stable. Keep v5.1.35 as the explicit rollback target for the v6.0.0 cutover.
+stable. The v6.0.0 cutover recorded v5.1.35 as its rollback target; that
+historical choice is not a safe downgrade procedure for a current installation.
## Before You Upgrade
-- Create an encrypted config backup: **Settings → System → Recovery → Create Backup** (older versions labeled this **Backups**)
-- Open **Settings → System → Updates** and review the upgrade checks on the update plan. Pulse checks the server update path, current agent continuity, and agent reporting token scope before you install. These checks describe the currently reported fleet; they do not prove every installed agent is online or already updated.
-- Confirm you can access the host/container console (for rollback and bootstrap token retrieval)
-- If the instance uses SSO without a configured local administrator, map a trusted IdP group to the built-in `admin` role before upgrading. SSO authentication alone does not grant instance-administrator access; an unmapped, `operator`, or `viewer` SSO session cannot manage settings, transfer configuration, or control infrastructure actions.
-- If you have any external integrations or scripts: review the **API Changes** section below
+- Keep a private, consistent backup of the existing installation's active data,
+ matching encryption/signing keys and deployment configuration. **Create Backup**
+ in **Settings → System → Recovery** (older versions labelled this **Backups**)
+ is a configuration export, **not a full-state backup**: history and agent
+ enrolment state are excluded. Follow [full-state recovery](MIGRATION.md#full-state-recovery);
+ do not copy live data or assume an updater snapshot includes every active store.
+- Confirm existing administrator access to Pulse and its host/container console.
+ Preserve credentials, connection state, agent identities and the existing
+ service and data/config paths. An upgrade does not require first-time setup.
+- Choose a maintenance window: updates interrupt monitoring and alert delivery.
+ Arrange independent coverage. Do not update during a backup, freeze/thaw or
+ an unresponsive-workload incident; use the [backup safety precaution](VM_DISK_MONITORING.md#backup-safety)
+ before restoring paused monitoring.
+- Open **Settings → System → Updates** and review the upgrade checks on the
+ update plan. These describe the currently reported fleet and server update
+ path, not every installed agent's continuity or convergence.
+- If the instance uses SSO without a configured local administrator, verify the
+ trusted IdP group's existing built-in `admin` mapping before upgrading. SSO
+ authentication alone does not grant instance-administrator access; an unmapped,
+ `operator` or `viewer` SSO session cannot manage settings or transfer configuration.
+ Do not remove role gating to repair a denial.
+- Review [API changes](#api-changes) for existing integrations and
+ [paid licensing connectivity](#breaking-change-paid-licensing-requires-connectivity)
+ before changing a paid installation. Preserve the private Pro runtime.
## Upgrade Paths
### systemd and Proxmox LXC installs
-Preferred path:
-
-- **Settings → System → Updates**
-
-If you prefer CLI, use this command only when `/bin/update` was installed by
-the Pulse server installer:
-
-```bash
-sudo /bin/update --version vX.Y.Z
-```
-
-On Proxmox community-scripts containers, `/bin/update` can belong to the
-community-scripts updater, which can ignore `--version`. If that is your
-installation, the helper is absent, or you cannot confirm its owner, follow the
-[signed server-installer flow](INSTALL.md#2-bare-metal--systemd) and set
-`PULSE_VERSION` to the exact target tag. This also applies to rollback. Verify
-the installed version with `GET /api/version` after the service restarts.
-
-Agent updates and v5-to-v6 agent upgrades use the `/install.sh` command generated
-in **Settings → Infrastructure → Install on a host**. That screen is for both
-first installs and in-place agent upgrades.
-
-Operator note for builds after `v6.0.0-rc.2`: the historical Pulse update
-signer was not recovered. Hosts pinned to the `rc.2` trust root should not
-assume unattended continuity into newer prerelease or GA artifacts; plan a
-manual reinstall or other explicit trust migration before testing those builds.
+Use **Settings → System → Updates** where supported. For CLI updates, follow
+[the existing-installation manual update procedure](INSTALL.md#manual-update):
+it checks the helper's ownership and preserves the existing service and
+data/config paths. Work inside the existing Pulse LXC, not on the Proxmox host
+or a monitored guest. Do not execute an absent or unknown helper; its filename
+`/bin/update` alone does not identify its owner or prove it accepts an exact version.
+Do not apply default installation paths over a custom deployment.
+
+If a community helper selects a Helm-chart asset, use
+[chart-selection recovery](AUTO_UPDATE.md#a-helper-selects-a-helm-chart-release),
+not another blind attempt, a GitHub token or a recreated LXC. The public signed
+server-installer flow is for Community; do not replace a private Pro runtime
+with it. Preserve the running version, edition and service health first.
+
+Agent updates and v5-to-v6 agent upgrades are separate from server updates.
+Use the [trusted-instance agent procedure](UNIFIED_AGENT.md#private-file-installation-linux-macos-and-nas)
+and **Settings → Infrastructure → Install on a host** for first installs and
+in-place agent upgrades; do not use the GitHub server installer for `pulse-agent`.
+
+For hosts pinned to `v6.0.0-rc.2`, the historical Pulse update signer was not
+recovered. This records a trust-continuity limit, not an instruction to reinstall
+or bypass signature verification. Arrange an explicit verified trust migration
+through the deployment's recovery procedure, preserving its identity, data and
+private edition; do not assume unattended continuity from that early trust root.
### Docker
-```bash
-docker pull rcourtman/pulse:vX.Y.Z
-docker compose up -d
-```
+Follow [Docker server updates](DOCKER.md#-updates) for the existing deployment.
+Change the configured image to the exact published tag first, then pull and
+recreate only the Pulse service, preserving mounted data, credentials and
+collector settings. Pulling a different tag does not change a hardcoded Compose
+image or the running container. Keep a private Pro image private; do not replace
+it with `rcourtman/pulse`. Do not run `docker compose down`, remove volumes or
+recreate unrelated services for a Pulse-only update.
### Kubernetes (Helm)
-```bash
-helm repo update
-helm upgrade pulse pulse/pulse -n pulse
-```
+Follow [the Helm deployment guidance](KUBERNETES.md#1-deploying-the-pulse-server),
+preserving the existing release, namespace, values and persistent volumes.
+Select the intended published chart and server image separately; a chart version
+alone does not establish the running server version or edition. Keep existing
+private Pro image configuration and Secret references; do not paste credentials
+into Helm command arguments or share resolved values or Secret YAML.
## Post-Upgrade Checklist
-- Confirm version: `GET /api/version`
-- Confirm scheduler health: `GET /api/monitoring/scheduler/health`
-- Confirm unified resources API is responding: `GET /api/resources`
-- Confirm nodes are polling and no breakers are stuck open
-- Confirm notifications still send (send a test)
-- Confirm agents are connected (if used)
+Use existing authenticated browser/API access and passive observations, not
+new diagnostic traffic or active probes just to fill this checklist. For API reads use an [authenticated browser or private
+header file](API.md#-authentication), never a token or session cookie in a
+command, URL or report.
+
+- Confirm the **running server version and edition**, not just the selected
+ release or a completed download. `GET /api/version` reports the server version;
+ a valid signature is not completed installation or healthy operation.
+- Observe ordinary polling, current readings and their original source/time.
+ A green connection badge or response from `/api/health` does not prove every
+ collector recovered. Read-only `GET /api/monitoring/scheduler/health` and
+ `GET /api/resources` can supplement, not replace, those observations.
+- Check ordinary notification delivery already observed and its destination/
+ resource identity. A successful Test does not prove ordinary delivery; do not
+ send a Test, trigger an alert or replay a queue just to complete this checklist.
+- Check agents individually where used. A current server does not prove that
+ every installed agent upgraded, authenticated or resumed reporting.
+- If monitoring was paused for backup safety, restore only its previously active
+ services/timers after independent thaw, every-covered-filesystem writes and
+ workload liveness checks pass. An OK backup task is not that proof.
+
+### Failed or interrupted upgrade
+
+Check the running version, edition and service health before another attempt.
+Keep the original attempt time/timezone, error and any already available updater
+or host stop evidence privately. A broken pipe does not establish why a service
+or its whole LXC stopped; a later boot is a new run, not the stop's cause.
+
+Use [update failure checks](AUTO_UPDATE.md#update-failed) and, if needed,
+[timer-only containment](AUTO_UPDATE.md#pause-further-unattended-attempts-without-stopping-pulse)
+without stopping a working Pulse server. Do not start, cancel or repeat an
+uncertain in-progress updater. Do not repeat the update, reboot, restore, run
+Diagnostics or delete rollback backups merely to obtain evidence.
+
+An older binary may not understand newer data. Use the
+[stopped-service recovery procedure](AUTO_UPDATE.md#manual-rollback) for matching
+data and keys, preserving reversible copies of the failed state. An image or
+binary change alone is not a data rollback. Share only relevant locally reviewed,
+redacted observations via [Getting Help](TROUBLESHOOTING.md#-getting-help), not
+backups, full logs or deployment configuration.
## v5 to v6 Operator FAQ
@@ -287,33 +349,27 @@ older v5 agents do not understand observer configuration.
### Can I keep Pulse v5 stable while I test Pulse v6?
-Yes. Keep a rollback path available while you evaluate v6. The final release
-on the v5 line is 5.1.36. On installations with the Pulse-owned update helper,
-the rollback command is:
-
-```bash
-sudo /bin/update --version v5.1.36
-```
+Keep the original installation and a verified recovery backup. Evaluate a
+restored copy only in an [isolated recovery instance](AUTO_UPDATE.md#manual-rollback)
+with no access to monitored systems or notification destinations; do not start
+a second connected copy. Moving the binary back does not reverse data migrated
+by v6. The final v5 release, v5.1.36, is end-of-life; it is historical context,
+not a supported recovery target for every current installation.
-The [installer ownership requirements](#systemd-and-proxmox-lxc-installs) above
-also apply to this command.
+Returning to an earlier version requires a deployment-specific recovery plan,
+matching data and keys, a compatible binary and the same edition. Follow the
+[rollback limits](INSTALL.md#rollback), not a generic `/bin/update` downgrade
+against the live migrated data.
### Why did my v5 install upgrade itself to v6?
-Pulse 5.1.29 and later pin the built-in updater to the 5.1.x line and never
-offer v6, so upgrading from those versions is always a manual step. Pulse
-5.1.28 and older have no such pin: installs with auto-update enabled follow
-the newest stable GitHub release, which is now v6. If that happened to you,
-your data and configuration carry over; run through the Post-Upgrade
-Checklist above to confirm everything still works. To return to v5 with the
-Pulse-owned update helper, run:
-
-```bash
-sudo /bin/update --version v5.1.36
-```
-
-For community-scripts installations or an unknown helper owner, use the
-[installer ownership guidance](#systemd-and-proxmox-lxc-installs) above.
+Pulse 5.1.29 and later pin the built-in updater to the 5.1.x line. Pulse 5.1.28
+and older have no such pin: an enabled updater can follow a newer stable release.
+This version-selection behaviour does not prove that the resulting upgrade or
+all collectors recovered. Check the running version and edition using the
+[post-upgrade checklist](#post-upgrade-checklist); preserve the original state
+and [recovery evidence](#failed-or-interrupted-upgrade) if anything remains wrong.
+Do not blindly run another updater or downgrade just because the target changed.
## Migration Notes (v6)
@@ -364,9 +420,10 @@ Pulse v6 feature gating is driven by the entitlements endpoint:
- `GET /api/license/entitlements`
For self-hosted v6, Pulse no longer sells monitored-system volume. Core
-monitoring stays available across Community, Relay, and Pro, while Relay and
-Pro sell convenience, history, AI operations, and advanced administration.
-Relay raises history to 14 days, while Pro raises it to 90 days.
+monitoring stays available across Community and Pro. Relay is no longer sold;
+existing Relay subscribers receive Pro features at their current price while
+their subscription continues. Preserve those entitlements and the private
+runtime when upgrading; see [current plans](PULSE_PRO.md).
Self-hosted v6 does not expose a general in-app trial, trial-return callback,
or hosted AI quickstart path. Ordinary upgraded self-hosted installs should use
@@ -449,7 +506,7 @@ When an existing paid user asks what changes for them specifically, use this rul
- Existing lifetime customers remain permanently valid, with self-hosted monitoring and child-resource volume not metered under the current v6 policy.
- Legacy paid v5 licenses migrated into v6 outside the recurring grandfathered path can still exchange into the v6 activation model without repurchasing. Migration records can preserve the original cohort for support and audit, but self-hosted monitoring volume is no longer the paid gate.
- Former recurring customers who already canceled, or who cancel and later return, do not resume the old grandfathered pricing automatically; they re-enter on current public v6 pricing for paid features while self-hosted monitoring remains included without a monitored-system volume gate.
-- New self-hosted v6 purchases use the current Community / Relay / Pro plan model with core monitoring included.
+- New self-hosted v6 purchases use the current Community / Pro plan model with core monitoring included; Relay is no longer sold.
If a self-hosted v6 install sees a new monitored-system, guest, or child-resource volume cap after moving to v6, treat that as a regression, not as expected upgrade behavior.
@@ -476,13 +533,13 @@ The migrations are additive:
- action audit records preserve execution and verification as separate truth.
Supported legacy JSON fields remain readable where older clients need them,
-but the primary v6 runtime has one writable owner for each domain. Pulse Mobile
-now reads the canonical Patrol attention queue. Operators should upgrade
-desktop and mobile clients together when they depend on acknowledgement,
-evidence, protection, or action-verification parity.
+but the primary v6 runtime has one writable owner for each domain. Server and
+agent/client versions remain separate; a server upgrade does not establish
+client convergence or every consuming surface's recovery.
-Before the upgrade, back up the Pulse data directory and confirm the service
-account can write the alert, notification, recovery, and action stores. After
+Before the upgrade, keep the consistent [full-state backup](MIGRATION.md#full-state-recovery)
+and confirm the existing service account can write the active stores without
+widening its permissions just to diagnose a failure. After
startup, verify that the Patrol navigation count matches the active queue,
inspect one evidence/protection drill-down, and confirm stale collection does
not appear resolved. Pulse Pro users should also verify entitlement
diff --git a/scripts/release_control/release_promotion_policy_test.py b/scripts/release_control/release_promotion_policy_test.py
index 8dfe96a5fc..cf96cbf8cf 100644
--- a/scripts/release_control/release_promotion_policy_test.py
+++ b/scripts/release_control/release_promotion_policy_test.py
@@ -1711,17 +1711,14 @@ class ReleasePromotionPolicyTest(unittest.TestCase):
server_updates = normalize_ws(
upgrade_guide.split("### systemd and Proxmox LXC installs", 1)[1].split("\n### ", 1)[0]
)
- self.assertIn("sudo /bin/update --version vX.Y.Z", server_updates)
- self.assertIn(
- "only when `/bin/update` was installed by the Pulse server installer",
- server_updates,
- )
- self.assertIn("community-scripts updater, which can ignore `--version`", server_updates)
- self.assertIn("the helper is absent, or you cannot confirm its owner", server_updates)
- self.assertIn("[signed server-installer flow](INSTALL.md#2-bare-metal--systemd)", server_updates)
- self.assertIn("`PULSE_VERSION` to the exact target tag", server_updates)
- self.assertIn("This also applies to rollback", server_updates)
- self.assertIn("Verify the installed version with `GET /api/version`", server_updates)
+ self.assertNotRegex(server_updates, r"```(?:bash|sh|shell)\b")
+ self.assertIn("INSTALL.md#manual-update", server_updates)
+ self.assertIn("helper's ownership", server_updates)
+ self.assertIn("Do not execute an absent or unknown helper", server_updates)
+ self.assertIn("default installation paths", server_updates)
+ self.assertIn("AUTO_UPDATE.md#a-helper-selects-a-helm-chart-release", server_updates)
+ self.assertIn("do not replace a private Pro runtime", server_updates)
+ self.assertIn("running version, edition and service health", server_updates)
def test_manual_update_help_preserves_helper_ownership_and_software_identity(self) -> None:
automatic_updates = read("docs/AUTO_UPDATE.md")
@@ -1774,7 +1771,9 @@ class ReleasePromotionPolicyTest(unittest.TestCase):
upgrade_guide = read("docs/UPGRADE_v6.md")
current_version = read("VERSION").strip()
self.assertIn("the historical Pulse update signer was not recovered", normalize_ws(upgrade_guide))
- self.assertIn("manual reinstall or other explicit trust migration", normalize_ws(upgrade_guide))
+ self.assertIn("explicit verified trust migration", normalize_ws(upgrade_guide))
+ self.assertIn("not an instruction to reinstall or bypass signature verification", normalize_ws(upgrade_guide))
+ self.assertIn("historical choice is not a safe downgrade procedure", normalize_ws(upgrade_guide))
self.assertIn("### License and Entitlements", upgrade_guide)
self.assertNotIn("### License, Trial, and Entitlements", upgrade_guide)
self.assertIn("does not expose a general in-app trial, trial-return callback, or hosted AI quickstart", normalize_ws(upgrade_guide))
diff --git a/scripts/tests/test_upgrade_v6_docs.py b/scripts/tests/test_upgrade_v6_docs.py
new file mode 100644
index 0000000000..c7d58fbcb9
--- /dev/null
+++ b/scripts/tests/test_upgrade_v6_docs.py
@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Keep the v6 migration entry point on safe, deployment-owned update paths.
+
+These are documentation and actual link-target controls, not native upgrade,
+rollback, collector recovery or private-runtime acceptance.
+"""
+from pathlib import Path
+import re
+import sys
+import unittest
+
+ROOT = Path(__file__).resolve().parents[2]
+GUIDE = ROOT / 'docs/UPGRADE_v6.md'
+sys.path.insert(0, str(ROOT / 'scripts'))
+from check_public_docs import anchors_for, split_target # noqa: E402
+
+
+def guide():
+ return GUIDE.read_text(encoding='utf-8')
+
+
+def section(heading, level='##'):
+ return guide().split(f'{level} {heading}\n', 1)[1].split(f'\n{level} ', 1)[0]
+
+
+def prose(text):
+ return ' '.join(text.split())
+
+
+class UpgradeV6DocsTest(unittest.TestCase):
+ def test_preparation_uses_full_state_not_configuration_export_or_live_copy(self):
+ before = prose(section('Before You Upgrade'))
+ for boundary in ('not a full-state backup', 'history and agent enrolment state',
+ 'matching encryption/signing keys', 'MIGRATION.md#full-state-recovery',
+ 'do not copy live data', 'every active store', 'existing service and data/config paths',
+ 'does not require first-time setup', 'interrupt monitoring and alert delivery',
+ 'independent coverage', 'Do not update during a backup, freeze/thaw'):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, before)
+
+ def test_update_routes_do_not_copy_unqualified_mutating_shortcuts(self):
+ routes = section('Upgrade Paths')
+ self.assertNotRegex(routes, r'```(?:bash|sh|shell)\b')
+ for boundary in ('INSTALL.md#manual-update', "helper's ownership", 'inside the existing Pulse LXC',
+ 'not on the Proxmox host', 'Do not execute an absent or unknown helper',
+ 'default installation paths', 'AUTO_UPDATE.md#a-helper-selects-a-helm-chart-release',
+ 'server-installer flow is for Community', 'do not replace a private Pro runtime',
+ 'separate from server updates', 'UNIFIED_AGENT.md#private-file-installation-linux-macos-and-nas',
+ 'do not use the GitHub server installer for `pulse-agent`'):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, prose(routes))
+
+ def test_docker_requires_configured_image_and_only_pulse_recreation(self):
+ docker = prose(section('Docker', '###'))
+ for boundary in ('DOCKER.md#-updates', 'Change the configured image', 'exact published tag first',
+ 'recreate only the Pulse service', 'mounted data, credentials',
+ 'does not change a hardcoded Compose image or the running container',
+ 'Keep a private Pro image private', 'Do not run `docker compose down`',
+ 'remove volumes', 'recreate unrelated services'):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, docker)
+
+ def test_kubernetes_preserves_existing_values_secrets_and_volume_scope(self):
+ helm = prose(section('Kubernetes (Helm)', '###').split('## Post-Upgrade Checklist', 1)[0])
+ for boundary in ('KUBERNETES.md#1-deploying-the-pulse-server',
+ 'existing release, namespace, values and persistent volumes',
+ 'published chart and server image separately', 'running server version or edition',
+ 'private Pro image configuration and Secret references',
+ 'do not paste credentials into Helm command arguments', 'Secret YAML'):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, helm)
+
+ def test_post_upgrade_does_not_create_notification_or_diagnostic_traffic(self):
+ post = prose(section('Post-Upgrade Checklist').split('### Failed or interrupted upgrade', 1)[0])
+ self.assertNotRegex(post.lower(), r'confirm notifications.*send a test')
+ for boundary in ('passive observations', 'API.md#-authentication', 'never a token or session cookie',
+ 'running server version and edition', 'not completed installation',
+ 'ordinary polling', 'original source/time', 'does not prove every collector recovered',
+ 'ordinary notification delivery', 'do not send a Test, trigger an alert or replay a queue',
+ 'Check agents individually', 'previously active services/timers',
+ 'every-covered-filesystem writes', 'An OK backup task is not that proof'):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, post)
+
+ def test_uncertain_update_retains_stop_evidence_and_does_not_repeat(self):
+ failure = prose(section('Failed or interrupted upgrade', '###').split('## v5 to v6 Operator FAQ', 1)[0])
+ for boundary in ('running version, edition and service health', 'original attempt time/timezone',
+ 'broken pipe does not establish', 'later boot is a new run',
+ 'AUTO_UPDATE.md#update-failed', 'AUTO_UPDATE.md#pause-further-unattended-attempts-without-stopping-pulse',
+ 'without stopping a working Pulse server', 'Do not start, cancel or repeat',
+ 'Do not repeat the update, reboot, restore, run Diagnostics or delete rollback backups',
+ 'AUTO_UPDATE.md#manual-rollback', 'matching data and keys',
+ 'reversible copies of the failed state', 'not a data rollback',
+ 'TROUBLESHOOTING.md#-getting-help', 'not backups, full logs or deployment configuration'):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, failure)
+
+ def test_historical_v5_downgrade_is_not_a_live_migrated_data_recipe(self):
+ faq = guide().split('### Can I keep Pulse v5 stable while I test Pulse v6?', 1)[1].split('## Migration Notes (v6)', 1)[0]
+ self.assertNotRegex(faq, r'```(?:bash|sh|shell)\b')
+ for boundary in ('isolated recovery instance', 'no access to monitored systems or notification destinations',
+ 'do not start a second connected copy', 'data migrated by v6',
+ 'v5.1.36, is end-of-life', 'not a supported recovery target', 'same edition',
+ 'INSTALL.md#rollback', 'live migrated data', 'version-selection behaviour does not prove',
+ 'Do not blindly run another updater or downgrade'):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, prose(faq))
+
+ def test_old_signer_warning_preserves_trust_without_reinstall_instruction(self):
+ routes = prose(section('Upgrade Paths'))
+ for boundary in ('historical Pulse update signer was not recovered', 'trust-continuity limit',
+ 'not an instruction to reinstall or bypass signature verification',
+ 'explicit verified trust migration', 'identity, data and private edition'):
+ self.assertIn(boundary, routes)
+ self.assertNotIn('plan a manual reinstall', routes)
+
+ def test_retired_relay_is_not_offered_as_a_new_upgrade_purchase(self):
+ licensing = prose(section('License and Entitlements', '###'))
+ self.assertNotIn('Community / Relay / Pro plan model', licensing)
+ self.assertNotIn('Relay raises history to 14 days', licensing)
+ for boundary in ('Relay is no longer sold', 'existing Relay subscribers receive Pro features',
+ 'current price while their subscription continues', 'private runtime'):
+ self.assertIn(boundary, licensing)
+
+ def test_connected_local_update_and_recovery_targets_exist(self):
+ links = re.findall(r'\[[^\]]*\]\(([^)]+)\)', guide())
+ required = ('INSTALL.md#manual-update', 'INSTALL.md#rollback', 'DOCKER.md#-updates',
+ 'MIGRATION.md#full-state-recovery', 'AUTO_UPDATE.md#manual-rollback',
+ 'AUTO_UPDATE.md#update-failed', 'KUBERNETES.md#1-deploying-the-pulse-server',
+ '#post-upgrade-checklist', '#failed-or-interrupted-upgrade')
+ for target in required:
+ with self.subTest(target=target):
+ self.assertIn(target, links)
+ path, anchor = split_target(target)
+ resolved = (GUIDE.parent / path).resolve() if path else GUIDE
+ self.assertTrue(resolved.is_file())
+ # The existing docs validator defers emoji-derived leading-hyphen
+ # aliases to the consuming browser; ordinary anchors remain exact.
+ if not anchor.startswith('-'):
+ self.assertIn(anchor, anchors_for(resolved))
+
+ def test_shipped_guide_is_byte_identical(self):
+ self.assertEqual(GUIDE.read_bytes(), (ROOT / 'frontend-modern/public/docs/UPGRADE_v6.md').read_bytes())
+
+
+if __name__ == '__main__':
+ unittest.main()