@pixlcore/xycli 1.2.0 → 1.2.2

package/.github/workflows/docker.yml

@@ -48,6 +48,7 @@ jobs:
         with:
           context: .
           file: ./Dockerfile
+          pull: true
           platforms: linux/amd64,linux/arm64
           push: true
           tags: ${{ steps.meta.outputs.tags }}

package/.github/workflows/offline-tests.yml

@@ -2,7 +2,7 @@ name: Offline Tests
 
 on:
   push:
-  pull_request:
+    tags: [ '*' ]
 
 permissions:
   contents: read

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # xyCLI Changelog
 
+## Version v1.2.1
+
+> October 29, 2026
+
+- [`c5b6e1c`](https://github.com/pixlcore/xycli/commit/c5b6e1c43296ba8d58d68ebee245b7d27dc4fbfb): Version 1.2.1
+- [`a2fca91`](https://github.com/pixlcore/xycli/commit/a2fca9138e5748d70b1e139b6d0b84f082ec7406): Feature: Follow live job retries automatically
+- [`6b3686d`](https://github.com/pixlcore/xycli/commit/6b3686d18c72139e32d18e1c90e10f8910565224): Feature: Set custom process title for MCP server.
+- [`099444b`](https://github.com/pixlcore/xycli/commit/099444bd87765c1a1e97a65bae6a2b2ea7f4f757): Add LICENSE.md file
+- [`2d6c1c4`](https://github.com/pixlcore/xycli/commit/2d6c1c44a73e265fba38b4feb1c2a7aaea843487): Meta: Fix offline test trigger to only run on tag pushes
+
+## Version v1.2.0
+
+> October 25, 2026
+
+- [`3f99851`](https://github.com/pixlcore/xycli/commit/3f9985186f3cba6e04c2fb0cc7b6eae3a7fc7fcb): Fix Windows MCP shutdown tests and update Node.js CI matrix
+- [`2034c48`](https://github.com/pixlcore/xycli/commit/2034c48626f999ffb969d4cebb7343cb233d565d): Version 1.2.0
+- [`e9693fb`](https://github.com/pixlcore/xycli/commit/e9693fbc527135b45ac2fc39659adb96923d9272): Feature: Expand MCP tools with tickets, alerts, snapshots and servers
+- [`1c12b76`](https://github.com/pixlcore/xycli/commit/1c12b76b747d97ccf358501d438e6deb8b97ca4e): Feature: Add Docker image and automated GHCR publishing for xyCLI
+- [`fa33af6`](https://github.com/pixlcore/xycli/commit/fa33af6b793786da33d6ae0bf832bcdea182e6b0): Feature: Add MCP server with shared STDIO and HTTP transports
+
+## Version v1.1.1
+
+> October 2, 2026
+
+- [`5f924c6`](https://github.com/pixlcore/xycli/commit/5f924c69ad8c5ed3c04be40d600b95fa3eee5f66): Version 1.1.1
+- [`759f8db`](https://github.com/pixlcore/xycli/commit/759f8db93f1763b7e876d16066b7dd04a9681ec3): Doc: Update xyOps version to v1.1.4 in two-way delete tutorial, and add in sys activity exclusions.
+- [`551be24`](https://github.com/pixlcore/xycli/commit/551be2413b4e584daebb2ed57710a620a7006372): Dep: Override "basic-ftp" (sub-sub-sub-sub-dep of pixl-request) to v6.2.1 for vuln fix, that isn't fixed in any of the parents.
+
+## Version v1.1.0
+
+> September 30, 2026
+
+- [`50ff6e6`](https://github.com/pixlcore/xycli/commit/50ff6e6f5f11a29287bcf0ffe2d8f7d966d34ee3): Version 1.1.0
+- [`5bf07a8`](https://github.com/pixlcore/xycli/commit/5bf07a87cfdc649abd8058c10f73c44b037c8cf4): Fix ticket unit test (due to API key bug fix over in xyOps)
+- [`5493608`](https://github.com/pixlcore/xycli/commit/5493608d71dbf8cfd9fbb3f2fef958d1bb107ee1): Feature: Down-sync delete mode, and a new two-way delete setup tut.
+
+## Version v1.0.9
+
+> September 28, 2026
+
+- [`9cbc6c7`](https://github.com/pixlcore/xycli/commit/9cbc6c753e9351243e13a942a3ad19c2012884cb): Version 1.0.9
+- [`6a0d739`](https://github.com/pixlcore/xycli/commit/6a0d739c3d85f61758bc9ea25c77a3b00968c79d): Feature: New system hook (syshook) deletion system, for active deletes from xyOps.
+- [`eeae786`](https://github.com/pixlcore/xycli/commit/eeae7863361c1f343dedae301a00d99db3fccdbb): Feature: New "--ignore_missing" parameter to suppress missing item warnings.  Fixes #9
+- [`80e77d4`](https://github.com/pixlcore/xycli/commit/80e77d40edfdb1c7fb4285235c6cc9fb2f0bcb2a): Bug Fix: Always print all errors and warnings, even in quiet mode.  Fixes #8
+
+## Version v1.0.8
+
+> September 25, 2026
+
+- [`3cc0914`](https://github.com/pixlcore/xycli/commit/3cc0914dd00211e6215ef3f2e5f7b2467570c9d0): Version 1.0.8
+- [`04d0f31`](https://github.com/pixlcore/xycli/commit/04d0f31eaee9b89bb5f2518c9bf813d24b5235eb): Meta: Fix offline unit tests on Windows (was using colon in filename)
+- [`5570628`](https://github.com/pixlcore/xycli/commit/557062875ab99a4cca41ae419204bc4992962ef1): Bug Fix: Remove some redundant dry run toasts.
+- [`536685e`](https://github.com/pixlcore/xycli/commit/536685eae72bc9bea1be24f4ba7e4998f17386fb): Feature: Allow buckets, bucket data and bucket files to all be synced.  Fixes #6
+- [`3cc2ccb`](https://github.com/pixlcore/xycli/commit/3cc2ccb93202bce52de6fe09dead7854ca274640): Docs: Added instructions for deleting items with two-way sync
+- [`38d336b`](https://github.com/pixlcore/xycli/commit/38d336b20797e435664924623e94d877a74c3c0a): Bug Fix: Allow unknown object properties to sync without error (i.e. for legacy Cronicle imports).
+- [`dc1e994`](https://github.com/pixlcore/xycli/commit/dc1e994c3b55eb4040210c8882cf01cd47b0defb): Bug FIx: For printing Emoji, do not use cursor save/restore width-fix when stdout is not a TTY.
+
+## Version v1.0.7
+
+> September 23, 2026
+
+- [`0cce2eb`](https://github.com/pixlcore/xycli/commit/0cce2eb70bc3f17e54fb19c8db43ce937701b68c): Version 1.0.7
+- [`4089e78`](https://github.com/pixlcore/xycli/commit/4089e78e9dc67894afa9d5c325af0e7c37e762a6): Bug Fix: Typo in custom job user HTML content when trying to rendering the caption.  Fixes #7.
+- [`76a247c`](https://github.com/pixlcore/xycli/commit/76a247c9abadeb9ee6f9c7bfb89d06cd375c41dd): Feature: Sync: Support workflow node sub-property neighbor files.  Fixes #5.
+
 ## Version v1.0.6
 
 > September 22, 2026

package/LICENSE.md

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026 PixlCore LLC & CONTRIBUTORS.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -243,7 +243,7 @@ xy job JOB_ID
 xy job log JOB_ID --download ./job-output.log
 ```
 
-You can also rerun a previous job with `xy job run JOB_ID --follow`, or resume a workflow job where supported. Job reports bring together results, performance, output, files, and workflow details.
+You can also rerun a previous job with `xy job run JOB_ID --follow`, or resume a workflow job where supported. When a job you are following fails and is retried, the CLI automatically follows the retry, continuing until the job succeeds or no further retry is scheduled. Job reports bring together results, performance, output, files, and workflow details.
 
 - **Command reference:** [Job searches](docs/help.md#jobs) and [Job operations](docs/help.md#job).
 - **Learn more about xyOps:** [xyOps Events and job execution](https://docs.xyops.io/events) and [xyOps Job data](https://docs.xyops.io/data#job).

package/docs/help.md

@@ -394,6 +394,8 @@ xy config --base_url http://localhost:5522 --api_key YOUR_API_KEY
 
 Updates load the user file separately and apply only the settings specified on the command line, preserving other user settings. System settings and environment overrides are not copied into the file. If the user file does not exist, it is created with only the supplied settings.
 
+Unknown top-level configuration keys are rejected before saving any changes, with a spelling suggestion when available. Use underscores in names such as `--base_url` and `--api_key`. Structured settings still support nested updates, such as `xy config --sync.down false` or `xy config --mcp.port 8080`.
+
 Configuration loads the machine file first, then the user file, then `XYOPS_`-prefixed environment variables. The machine and user files are `/etc/xyops/cli.json` and `~/.config/xyops/cli.json` on Unix and macOS, or `%PROGRAMDATA%\xyops\cli.json` and `%USERPROFILE%\.config\xyops\cli.json` on Windows. Later sources override matching top-level settings. Environment overrides still take precedence over saved user settings. Common keys include `api_key`, `base_url`, `temp_dir`, `color`, `suggest`, `items_per_page`, `cache_ttl`, `raw`, and `invisible`.
 
 Environment values that look like JSON objects or arrays are parsed automatically for any setting. For example, `XYOPS_SYNC='{"up":["events"],"down":false}'` supplies a structured `sync` setting. Boolean and numeric values keep their usual conversions. Malformed JSON-looking values report the environment variable name. Objects and arrays are serialized as JSON when the CLI exports its effective configuration back into the environment.

package/index.js

@@ -203,7 +203,8 @@ const app = {
 		delete args.format;
 		
 		this.raw = args.raw || this.config.raw || false;
-		delete args.raw;
+		// The config command saves --raw as a preference for future commands.
+		if (cmd != 'config') delete args.raw;
 		
 		this.dry = args.dry || false;
 		delete args.dry;

package/lib/config.js

@@ -7,6 +7,27 @@ const cli = require('pixl-cli');
 const Tools = cli.Tools;
 const chalk = cli.chalk;
 
+// Settings consumed by the CLI, MCP server, or SDK.  Keep this inventory
+// explicit so a typo already saved in a config file cannot become a valid key.
+const CONFIG_KEYS = [
+	'api_key', 'base_url', 'temp_dir', 'color', 'suggest', 'items_per_page',
+	'cache_ttl', 'raw', 'invisible', 'tz', 'log_columns', 'new_event_template',
+	'sync', 'mcp', 'user_agent', 'timeout', 'connect_timeout', 'idle_timeout',
+	'retries', 'retry_delay', 'retry_delay_max', 'allow_unauthorized',
+	'mcp_host', 'mcp_port', 'mcp_read_only', 'mcp_max_page_size',
+	'mcp_max_result_bytes', 'mcp_max_request_bytes', 'mcp_tls_cert', 'mcp_tls_key',
+	'ui', 'default_user_privileges', 'max_servers_per_group', 'quick_monitors',
+	'job_universal_actions', 'job_universal_limits'
+];
+
+// Structured settings also support the existing dot and slash path syntax.
+// Their contents may include arbitrary plugin parameters or server UI data.
+const CONFIG_PATH_KEYS = [
+	'log_columns', 'new_event_template', 'sync', 'mcp', 'ui',
+	'default_user_privileges', 'quick_monitors', 'job_universal_actions',
+	'job_universal_limits'
+];
+
 function getConfigFiles(platform, env, home_dir) {
 	// Keep the existing Unix paths, but use Windows's shared application-data
 	// directory instead of resolving /etc against whichever drive is current.
@@ -66,6 +87,9 @@ var config_layer = module.exports = {
 		// allow user to view config, and also modify it
 		delete this.args.other;
 		
+		// These flags control this invocation, rather than saved preferences.
+		for (var key of ['debug', 'echo', 'quiet', 'verbose']) delete this.args[key];
+		
 		if (!Tools.firstKey(this.args)) {
 			// just print config and exit
 			println( "\n " + this.color('theme').bold( 'CONFIGURATION SOURCES:' ) + "\n" );
@@ -81,6 +105,18 @@ var config_layer = module.exports = {
 			return;
 		}
 		
+		// Validate the entire update before printing any values or touching the
+		// file.  In particular, a misspelled --api-key must never echo its secret.
+		for (var key of Object.keys(this.args)) {
+			var root = key.split(/[.\/]/)[0];
+			if (CONFIG_KEYS.includes(key) || ((root != key) && CONFIG_PATH_KEYS.includes(root))) continue;
+			
+			var suggestion = this.findClosestString(root, (root == key) ? CONFIG_KEYS : CONFIG_PATH_KEYS);
+			var message = 'Unknown configuration key "' + key + '".';
+			if (suggestion) message += ' Did you mean "' + suggestion + ((root != key) ? key.slice(root.length) : '') + '"?';
+			return this.die(message);
+		}
+		
 		// Reload only the user's settings before applying changes.  The effective
 		// configuration also contains system settings and environment overrides,
 		// which must not be copied into the user's file when saving preferences.

package/lib/jobs.js

@@ -173,7 +173,7 @@ module.exports = {
 		// check if job is still active
 		if (job.final) {
 			// job must have completed, hop over to job details
-			return await this.cmd_get_job();
+			return await this.cmd_get_job(true);
 		}
 		
 		// print def list of job summary data
@@ -231,10 +231,10 @@ module.exports = {
 		
 		// this.printJobCompletionBanner(job);
 		// delete this.activeJobs[this.args.id];
-		await this.cmd_get_job();
+		await this.cmd_get_job(true);
 	},
 	
-	async cmd_get_job() {
+	async cmd_get_job(follow = false) {
 		// get job progress or result
 		if (this.args.other && this.args.other.length && !this.args.id) {
 			this.args.id = this.args.other.shift();
@@ -255,6 +255,24 @@ module.exports = {
 			return await this.cmd_stream_job();
 		}
 		
+		// A live follow continues through retries using the completed record,
+		// which includes additional jobs that may be absent from stream updates.
+		// Ordinary lookups of completed jobs still display the requested attempt.
+		if (follow && job.code && Array.isArray(job.jobs)) {
+			var retry = job.jobs.find( item => item && item.id && (item.reason === 'retry') );
+			if (retry) {
+				if (!this.format.match(/json/)) {
+					this.printJobCompletionBanner(job);
+					println( "\n " + yellow.bold("Following retry: ") + this.getNiceJob(retry.id) );
+				}
+				
+				// Reuse the stream entry point so queued retries and attempts that
+				// already finished before we attached are handled the same way.
+				this.args.id = retry.id;
+				return await this.cmd_stream_job();
+			}
+		}
+		
 		if (this.format.match(/json/)) {
 			return this.jsonOutput(job);
 		}

package/lib/mcp.js

@@ -44,6 +44,9 @@ function configuration(config, args) {
 }
 
 async function main(argv) {
+	// Give the long-running MCP server a recognizable name in process lists.
+	process.title = 'xyOps MCP Server';
+	
 	const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: {
 		port: { type: 'string' }, host: { type: 'string' }, 'read-only': { type: 'boolean' },
 		'tls-cert': { type: 'string' }, 'tls-key': { type: 'string' },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pixlcore/xycli",
-	"version": "1.2.0",
+	"version": "1.2.2",
 	"description": "A complete command-line interface for the xyOps workflow automation system.",
 	"author": "Joseph Huckaby <jhuckaby@pixlcore.com>",
 	"homepage": "https://github.com/pixlcore/xycli",
@@ -21,7 +21,7 @@
 	],
 	"scripts": {
 		"test": "node test.js",
-		"test:offline": "node --test test/config.test.js test/help.test.js test/markdown.test.js test/sync-buckets-unit.test.js test/sync-syshook-unit.test.js test/sync-unit.test.js test/toast.test.js test/upgrade.test.js test/utils-unit.test.js test/mcp-tools-unit.test.js test/mcp-stdio-unit.test.js test/mcp-http-unit.test.js",
+		"test:offline": "node --test test/config.test.js test/help.test.js test/jobs-follow-unit.test.js test/markdown.test.js test/sync-buckets-unit.test.js test/sync-syshook-unit.test.js test/sync-unit.test.js test/toast.test.js test/upgrade.test.js test/utils-unit.test.js test/mcp-tools-unit.test.js test/mcp-stdio-unit.test.js test/mcp-http-unit.test.js",
 		"changelog": "node tools/changelog.js"
 	},
 	"overrides": {

package/test/README.md

@@ -59,6 +59,7 @@ node --test test/config.test.js test/sync-buckets-unit.test.js test/sync-unit.te
 | `config` | Offline user-file updates, inherited-setting isolation, missing-file creation, dotted edits, permissions, and read-only display |
 | `events` | CRUD, dependency filters, nested edits, triggers, actions, limits, fields, validation, and help |
 | `jobs` | Event launch, parameter and input overrides, completed reports, output logs, search, rerun, deletion, validation, and help |
+| `jobs-follow-unit` | Offline live-follow retry chains, queued and already-completed retries, completed-job lookups, and stopping without a retry |
 | `log` | Log searches, latest rows, matching, column selection, native output |
 | `markdown` | Terminal rendering, inline formatting inside list items, typographic bullets, and output margins |
 | `monitors` | CRUD, groups, evaluator requests, type conversions, validation, help |

package/test/config.test.js

@@ -32,7 +32,7 @@ function createConfigFixture(t, initial) {
 	
 	return {
 		file,
-		run(args) {
+		run(args, expected_status = 0) {
 			const env = {
 				...process.env,
 				HOME: home_dir,
@@ -58,8 +58,8 @@ function createConfigFixture(t, initial) {
 			// Keep captured CLI output out of assertion messages, since a config
 			// command may display settings inherited from the real system file.
 			assert.ifError(result.error);
-			assert.equal(result.status, 0, 'Config command should succeed');
-			return result.stdout;
+			assert.equal(result.status, expected_status, 'Config command should exit with the expected status');
+			return result.stdout + result.stderr;
 		},
 		read() { return JSON.parse(fs.readFileSync(file, 'utf8')); }
 	};
@@ -112,6 +112,65 @@ test('config creates a missing user file with only supplied settings', t => {
 	assertPrivateMode(fixture.file);
 });
 
+test('config rejects misspelled keys without creating a file or exposing secrets', t => {
+	const fixture = createConfigFixture(t);
+	
+	for (const [key, suggestion] of [['base-url', 'base_url'], ['api-key', 'api_key'], ['items_per_pag', 'items_per_page']]) {
+		const output = fixture.run(['--' + key, 'private-fixture-value'], 1);
+		assert.ok(output.includes('Unknown configuration key "' + key + '".'));
+		assert.ok(output.includes('Did you mean "' + suggestion + '"?'));
+		assert.doesNotMatch(output, /private-fixture-value|Setting key:|Writing to:/);
+		assert.equal(fs.existsSync(fixture.file), false);
+	}
+});
+
+test('config rejects mixed valid and unknown updates without changing the user file', t => {
+	// Previously saved typos must not be accepted as supported config keys.
+	const fixture = createConfigFixture(t, { items_per_page: 10, 'api-key': 'old-value' });
+	const original = fs.readFileSync(fixture.file, 'utf8');
+	const output = fixture.run(['--items_per_page', '25', '--api-key', 'private-fixture-value'], 1);
+	
+	assert.match(output, /Unknown configuration key "api-key"/);
+	assert.doesNotMatch(output, /private-fixture-value|Setting key:|Writing to:/);
+	assert.equal(fs.readFileSync(fixture.file, 'utf8'), original);
+});
+
+test('config rejects unrelated keys and nested paths under scalar settings', t => {
+	const fixture = createConfigFixture(t);
+	
+	for (const key of ['unrelated_option', 'api_key.child', 'base_url/child']) {
+		const output = fixture.run(['--' + key, 'private-fixture-value'], 1);
+		assert.match(output, /Unknown configuration key/);
+		assert.doesNotMatch(output, /private-fixture-value|Setting key:|Writing to:/);
+		assert.equal(fs.existsSync(fixture.file), false);
+	}
+});
+
+test('config saves supported connection, SDK, MCP, and structured settings', t => {
+	const fixture = createConfigFixture(t);
+	const output = fixture.run([
+		'--base_url', 'https://saved.invalid', '--api_key', 'private-fixture-value',
+		'--timeout', '5000', '--mcp_port', '8080', '--mcp.read_only', 'true',
+		'--new_event_template/params/custom', 'value', '--raw', 'false'
+	]);
+	
+	assert.doesNotMatch(output, /private-fixture-value/);
+	assert.deepEqual(fixture.read(), {
+		base_url: 'https://saved.invalid', api_key: 'private-fixture-value',
+		timeout: 5000, mcp_port: 8080, mcp: { read_only: true },
+		new_event_template: { params: { custom: 'value' } }, raw: false
+	});
+	assertPrivateMode(fixture.file);
+});
+
+test('config ignores invocation flags when displaying and saving settings', t => {
+	const fixture = createConfigFixture(t);
+	fixture.run(['--quiet']);
+	assert.equal(fs.existsSync(fixture.file), false);
+	fixture.run(['--verbose', '--items_per_page', '25']);
+	assert.deepEqual(fixture.read(), { items_per_page: 25 });
+});
+
 test('config dotted updates preserve sibling user settings and explicit false or zero values', t => {
 	const fixture = createConfigFixture(t, {
 		sync: { up: ['events'], down: ['plugins'], error_email: 'ops@example.com' },

package/test/jobs-follow-unit.test.js

@@ -0,0 +1,107 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const cli = require('pixl-cli');
+const jobs = require('../lib/jobs.js');
+
+cli.global();
+
+function makeFollower(t, records) {
+	// Exercise the real command transitions with an offline SDK stub.  Streaming
+	// finishes an attempt, but only getJob exposes its additional-job links.
+	const streamed = [];
+	const results = [];
+	const context = {
+		...jobs,
+		args: { id: records[0].id },
+		format: 'json',
+		async getMultiple() {},
+		api: {
+			async getJob({ id }) {
+				const job = records.find( item => item.id === id );
+				assert.ok(job, 'Unexpected job lookup: ' + id);
+				return { data: { job: { ...job } } };
+			},
+			async streamJob({ id }, callback) {
+				const job = records.find( item => item.id === id );
+				streamed.push(id);
+				job.final = true;
+				callback({ id, final: true, code: job.code });
+				return {};
+			}
+		},
+		jsonOutput(job) { results.push(job.id); },
+		die(message) { throw new Error(message); },
+		color() { return cli.chalk.white; },
+		printBoxList() {}
+	};
+	
+	// Keep terminal rendering out of these tests, including progress timers.
+	for (const name of ['start', 'update', 'end']) t.mock.method(cli.progress, name, () => {});
+	for (const name of ['print', 'println', 'verboseln']) t.mock.method(global, name, () => {});
+	for (const name of ['getNiceJob', 'getNiceJobEvent', 'getNiceCategory', 'getNicePlugin',
+		'getNiceTargets', 'getNiceServer', 'getNiceAlgo', 'getNiceJobSource',
+		'getRelativeDateTime', 'getNiceJobState']) {
+		context[name] = () => '';
+	}
+	
+	return { context, streamed, results };
+}
+
+test('live follow crosses completed and queued retries, ignoring unrelated jobs', async t => {
+	const { context, streamed, results } = makeFollower(t, [
+		{ id: 'initial', code: 1, jobs: [{ id: 'other', reason: 'action' }, { id: 'retry1', reason: 'retry' }] },
+		{ id: 'retry1', final: true, code: 'warning', jobs: [{ id: 'retry2', reason: 'retry' }] },
+		{ id: 'retry2', state: 'queued', code: 0 }
+	]);
+	
+	await context.cmd_stream_job();
+	assert.deepEqual(streamed, ['initial', 'retry2']);
+	assert.deepEqual(results, ['retry2']);
+});
+
+test('directly opening an active job also follows its retry', async t => {
+	const { context, streamed, results } = makeFollower(t, [
+		{ id: 'initial', code: 1, jobs: [{ id: 'retry', reason: 'retry' }] },
+		{ id: 'retry', code: 2 }
+	]);
+	
+	await context.cmd_get_job();
+	assert.deepEqual(streamed, ['initial', 'retry']);
+	assert.deepEqual(results, ['retry']);
+});
+
+test('follow catches retries when the initial job finishes before streaming starts', async t => {
+	const { context, streamed, results } = makeFollower(t, [
+		{ id: 'initial', final: true, code: 1, jobs: [{ id: 'retry', reason: 'retry' }] },
+		{ id: 'retry', code: 0 }
+	]);
+	
+	await context.cmd_stream_job();
+	assert.deepEqual(streamed, ['retry']);
+	assert.deepEqual(results, ['retry']);
+});
+
+test('opening a completed job preserves the requested attempt', async t => {
+	const { context, streamed, results } = makeFollower(t, [
+		{ id: 'initial', final: true, code: 1, jobs: [{ id: 'retry', reason: 'retry' }] }
+	]);
+	
+	await context.cmd_get_job();
+	assert.deepEqual(streamed, []);
+	assert.deepEqual(results, ['initial']);
+});
+
+test('follow stops on success or failure without a valid retry link', async t => {
+	for (const record of [
+		{ code: 0, jobs: [{ id: 'other', reason: 'retry' }] },
+		{ code: 1 },
+		{ code: 1, jobs: [] },
+		{ code: 1, jobs: {} },
+		{ code: 1, jobs: [null, { reason: 'retry' }, { id: 'other', reason: 'action' }] }
+	]) {
+		const { context, streamed, results } = makeFollower(t, [{ id: 'initial', ...record }]);
+		await context.cmd_stream_job();
+		assert.deepEqual(streamed, ['initial']);
+		assert.deepEqual(results, ['initial']);
+	}
+});