nomadctl 0.2.0__tar.gz → 0.4.0__tar.gz

{nomadctl-0.2.0 → nomadctl-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nomadctl
-Version: 0.2.0
+Version: 0.4.0
 Summary: A friendly command-line tool for managing a HashiCorp Nomad homelab cluster.
 Keywords: cli,devops,hashicorp,homelab,nomad,orchestration
 Author: Nathaniel Landau
@@ -17,13 +17,13 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
-Requires-Dist: httpx2>=2.4.0,<3.0.0
+Requires-Dist: httpx2>=2.5.0,<3.0.0
 Requires-Dist: lark>=1.3.1,<2.0.0
 Requires-Dist: msgspec>=0.21.1
 Requires-Dist: nclutils>=3.4.1,<4.0.0
 Requires-Dist: python-hcl2>=8.1.2,<9.0.0
 Requires-Dist: rich>=15.0.0
-Requires-Dist: typer>=0.26.7
+Requires-Dist: typer>=0.26.8
 Requires-Python: >=3.13, <3.15
 Project-URL: Homepage, https://github.com/natelandau/nd
 Project-URL: Issues, https://github.com/natelandau/nd/issues
@@ -60,9 +60,9 @@ your easy to remember job and volume names and the cli does the rest.
 
 - Python 3.13 or 3.14.
 - A reachable Nomad cluster.
-- The `nomad` binary on your `PATH`. The `plan`, `run`, `exec`, and `logs` commands
-  shell out to it, because the HTTP API cannot parse HCL2 job files and does not own
-  the interactive exec protocol. The other commands use the API only.
+- The `nomad` binary on your `PATH`. The `plan`, `run`, `update`, `exec`, and `logs`
+  commands shell out to it, because the HTTP API cannot parse HCL2 job files and does
+  not own the interactive exec protocol. The other commands use the API only.
 
 ## Installation
 
@@ -171,6 +171,7 @@ Run `nd --help`, or `nd <command> --help`, for the full option list at any time.
 | `nd list`                   | List discovered job files and whether each is running, dead, or not deployed.     |
 | `nd plan [JOB]`             | Preview the changes one or more job files would apply, including to running jobs. |
 | `nd run [JOB]`              | Deploy not-yet-running job files and watch the rollout.                           |
+| `nd update [JOB]`           | Recreate a running job from its local file and watch the rollout.                 |
 | `nd stop [JOB]`             | Stop, and optionally purge, running jobs and watch them drain.                    |
 | `nd logs [JOB]`             | Stream, tail, or export a task's logs.                                            |
 | `nd exec [JOB]`             | Open an interactive shell inside a running task.                                  |
@@ -181,12 +182,13 @@ Run `nd --help`, or `nd <command> --help`, for the full option list at any time.
 
 ### Targeting jobs by name
 
-Commands that take a `JOB` or `NAME` argument match by case-insensitive name prefix.
+Commands that take a `JOB` or `NAME` argument match by case-insensitive substring:
+any name that contains the text matches, so `web` finds both `web` and `reverse-web`.
 A single match runs straight away; several matches open a prompt. Omit the argument
 to pick from a list of every candidate.
 
 ```bash
-nd run web          # runs the one job whose name starts with "web"
+nd run web          # runs the job whose name contains "web" (prompts if several match)
 nd stop             # prompts you to choose from all running jobs
 ```
 
@@ -197,12 +199,13 @@ touching the cluster:
 
 ```bash
 nd run --dry-run
+nd update web --dry-run
 nd stop web --dry-run
 nd volume register --dry-run
 ```
 
-For `nd run`, a dry run still validates each job file locally, so it catches a
-broken spec without registering anything.
+For `nd run` and `nd update`, a dry run still validates each job file locally, so it
+catches a broken spec without registering anything.
 
 ### Deploying jobs
 
@@ -212,10 +215,34 @@ settle. Use `--detach` to register and return without watching the rollout.
 
 ```bash
 nd run                # choose from every deployable job
-nd run web            # deploy the job whose name starts with "web"
+nd run web            # deploy the job whose name contains "web"
 nd run web --detach   # register and return immediately
 ```
 
+### Updating jobs
+
+`nd update` recreates a job that is already running. Reach for it to roll out an
+edited job file, or to pull a fresh version when the file is unchanged, such as a
+container that tracks a moving tag. It only offers jobs that are both running and
+have a local file.
+
+Each selected job is stopped, drained, purged, then re-registered from its local
+file and watched until the new rollout settles. The job is fully recreated, so
+expect brief downtime. `nd update` confirms before it acts unless you pass `--force`
+(`-f`), and purges by default (unlike `nd stop`, which keeps the job unless you pass
+`--purge`); pass `--no-purge` to keep the job's version history.
+
+```bash
+nd update                 # choose from every running job that has a local file
+nd update web             # recreate the job whose name contains "web"
+nd update web --no-purge  # recreate but keep the version history
+nd update web --force     # skip the confirmation prompt
+```
+
+Whether a new container image is actually pulled depends on the job's Docker driver
+config, such as `force_pull` or a pinned digest, not on `nd`. The recreate
+guarantees fresh allocations; the image policy stays with your job spec.
+
 ### Working with logs
 
 `nd logs` streams both stdout and stderr live until you press Ctrl-C. Narrow or
@@ -241,6 +268,21 @@ nd stop web --purge --force       # purge without a prompt
 nd stop web --detach              # request the stop and return immediately
 ```
 
+### Managing host volumes
+
+`nd volume register` and `nd volume delete` create and remove dynamic host volumes
+from your local spec files, and `nd volume list` shows where each spec is registered.
+Deleting a host volume is irreversible and orphans data for any job that mounts it,
+so `nd volume delete` confirms before it acts unless you pass `--force` (`-f`); a
+`--dry-run` (`-n`) previews the registrations that would be removed without prompting.
+
+```bash
+nd volume register data            # register the "data" volume on eligible nodes
+nd volume delete data              # confirm, then delete the "data" registrations
+nd volume delete data --force      # delete without a prompt
+nd volume delete data --dry-run    # preview what would be deleted
+```
+
 ### Verbosity
 
 Add `-v` for debug output or `-vv` to trace each API request with timings. The flag

{nomadctl-0.2.0 → nomadctl-0.4.0}/README.md

@@ -28,9 +28,9 @@ your easy to remember job and volume names and the cli does the rest.
 
 - Python 3.13 or 3.14.
 - A reachable Nomad cluster.
-- The `nomad` binary on your `PATH`. The `plan`, `run`, `exec`, and `logs` commands
-  shell out to it, because the HTTP API cannot parse HCL2 job files and does not own
-  the interactive exec protocol. The other commands use the API only.
+- The `nomad` binary on your `PATH`. The `plan`, `run`, `update`, `exec`, and `logs`
+  commands shell out to it, because the HTTP API cannot parse HCL2 job files and does
+  not own the interactive exec protocol. The other commands use the API only.
 
 ## Installation
 
@@ -139,6 +139,7 @@ Run `nd --help`, or `nd <command> --help`, for the full option list at any time.
 | `nd list`                   | List discovered job files and whether each is running, dead, or not deployed.     |
 | `nd plan [JOB]`             | Preview the changes one or more job files would apply, including to running jobs. |
 | `nd run [JOB]`              | Deploy not-yet-running job files and watch the rollout.                           |
+| `nd update [JOB]`           | Recreate a running job from its local file and watch the rollout.                 |
 | `nd stop [JOB]`             | Stop, and optionally purge, running jobs and watch them drain.                    |
 | `nd logs [JOB]`             | Stream, tail, or export a task's logs.                                            |
 | `nd exec [JOB]`             | Open an interactive shell inside a running task.                                  |
@@ -149,12 +150,13 @@ Run `nd --help`, or `nd <command> --help`, for the full option list at any time.
 
 ### Targeting jobs by name
 
-Commands that take a `JOB` or `NAME` argument match by case-insensitive name prefix.
+Commands that take a `JOB` or `NAME` argument match by case-insensitive substring:
+any name that contains the text matches, so `web` finds both `web` and `reverse-web`.
 A single match runs straight away; several matches open a prompt. Omit the argument
 to pick from a list of every candidate.
 
 ```bash
-nd run web          # runs the one job whose name starts with "web"
+nd run web          # runs the job whose name contains "web" (prompts if several match)
 nd stop             # prompts you to choose from all running jobs
 ```
 
@@ -165,12 +167,13 @@ touching the cluster:
 
 ```bash
 nd run --dry-run
+nd update web --dry-run
 nd stop web --dry-run
 nd volume register --dry-run
 ```
 
-For `nd run`, a dry run still validates each job file locally, so it catches a
-broken spec without registering anything.
+For `nd run` and `nd update`, a dry run still validates each job file locally, so it
+catches a broken spec without registering anything.
 
 ### Deploying jobs
 
@@ -180,10 +183,34 @@ settle. Use `--detach` to register and return without watching the rollout.
 
 ```bash
 nd run                # choose from every deployable job
-nd run web            # deploy the job whose name starts with "web"
+nd run web            # deploy the job whose name contains "web"
 nd run web --detach   # register and return immediately
 ```
 
+### Updating jobs
+
+`nd update` recreates a job that is already running. Reach for it to roll out an
+edited job file, or to pull a fresh version when the file is unchanged, such as a
+container that tracks a moving tag. It only offers jobs that are both running and
+have a local file.
+
+Each selected job is stopped, drained, purged, then re-registered from its local
+file and watched until the new rollout settles. The job is fully recreated, so
+expect brief downtime. `nd update` confirms before it acts unless you pass `--force`
+(`-f`), and purges by default (unlike `nd stop`, which keeps the job unless you pass
+`--purge`); pass `--no-purge` to keep the job's version history.
+
+```bash
+nd update                 # choose from every running job that has a local file
+nd update web             # recreate the job whose name contains "web"
+nd update web --no-purge  # recreate but keep the version history
+nd update web --force     # skip the confirmation prompt
+```
+
+Whether a new container image is actually pulled depends on the job's Docker driver
+config, such as `force_pull` or a pinned digest, not on `nd`. The recreate
+guarantees fresh allocations; the image policy stays with your job spec.
+
 ### Working with logs
 
 `nd logs` streams both stdout and stderr live until you press Ctrl-C. Narrow or
@@ -209,6 +236,21 @@ nd stop web --purge --force       # purge without a prompt
 nd stop web --detach              # request the stop and return immediately
 ```
 
+### Managing host volumes
+
+`nd volume register` and `nd volume delete` create and remove dynamic host volumes
+from your local spec files, and `nd volume list` shows where each spec is registered.
+Deleting a host volume is irreversible and orphans data for any job that mounts it,
+so `nd volume delete` confirms before it acts unless you pass `--force` (`-f`); a
+`--dry-run` (`-n`) previews the registrations that would be removed without prompting.
+
+```bash
+nd volume register data            # register the "data" volume on eligible nodes
+nd volume delete data              # confirm, then delete the "data" registrations
+nd volume delete data --force      # delete without a prompt
+nd volume delete data --dry-run    # preview what would be deleted
+```
+
 ### Verbosity
 
 Add `-v` for debug output or `-vv` to trace each API request with timings. The flag

{nomadctl-0.2.0 → nomadctl-0.4.0}/pyproject.toml

@@ -13,13 +13,13 @@
         "Typing :: Typed",
     ]
     dependencies = [
-        "httpx2>=2.4.0,<3.0.0",
+        "httpx2>=2.5.0,<3.0.0",
         "lark>=1.3.1,<2.0.0",
         "msgspec>=0.21.1",
         "nclutils>=3.4.1,<4.0.0",
         "python-hcl2>=8.1.2,<9.0.0",
         "rich>=15.0.0",
-        "typer>=0.26.7",
+        "typer>=0.26.8",
     ]
     description = "A friendly command-line tool for managing a HashiCorp Nomad homelab cluster."
     keywords = ["cli", "devops", "hashicorp", "homelab", "nomad", "orchestration"]
@@ -28,7 +28,7 @@
     name = "nomadctl"
     readme = "README.md"
     requires-python = ">=3.13, <3.15"
-    version = "0.2.0"
+    version = "0.4.0"
 
     [project.urls]
         Homepage   = "https://github.com/natelandau/nd"
@@ -62,9 +62,9 @@
         "pytest-sugar>=1.1.1",
         "pytest>=9.1.1",
         "respx>=0.23.1",
-        "ruff>=0.15.18",
-        "ty>=0.0.52",
-        "typos>=1.47.2",
+        "ruff>=0.15.20",
+        "ty>=0.0.55",
+        "typos>=1.48.0",
         "yamllint>=1.38.0",
     ]
 

{nomadctl-0.2.0 → nomadctl-0.4.0}/src/nd/__init__.py

@@ -1,6 +1,6 @@
 """The nd package."""
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 
 from nd.cli import main
 

{nomadctl-0.2.0 → nomadctl-0.4.0}/src/nd/cli.py

@@ -9,7 +9,7 @@ import typer
 from nclutils import pp
 
 from nd import __version__
-from nd.commands import clean, exec, logs, plan, run, status, stop, volume  # noqa: A004
+from nd.commands import clean, exec, logs, plan, run, status, stop, update, volume  # noqa: A004
 from nd.commands import list as list_cmd
 from nd.nomad import (
     NomadAuthError,
@@ -28,6 +28,7 @@ app.add_typer(clean.app, name="clean")
 app.add_typer(list_cmd.app, name="list")
 app.add_typer(plan.app, name="plan")
 app.add_typer(run.app, name="run")
+app.add_typer(update.app, name="update")
 app.add_typer(logs.app, name="logs")
 app.add_typer(exec.app, name="exec")
 app.add_typer(volume.app, name="volume")

nomadctl-0.4.0/src/nd/commands/_orchestration.py

@@ -0,0 +1,106 @@
+"""Shared scaffolding for the job-lifecycle commands (``run``, ``stop``, ``update``).
+
+These three commands share the same shape: resolve node names once, optionally
+confirm, run every target under one live panel, then emit durable lines for the
+outcomes that did not finish cleanly and compute an exit code. This module owns
+that scaffolding so each command keeps only its own vocabulary (its status enum,
+outcome type, and the labels it shows).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from nclutils import pp
+
+from nd.ui.duration import summary_title
+from nd.ui.prompts import select_one
+from nd.ui.styles import OUTCOME_GLYPH
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+    from nd.nomad import NomadClient
+
+
+async def node_names_by_id(client: NomadClient) -> dict[str, str]:
+    """Map node IDs to node names so a live panel's detail rows can show placement.
+
+    Fetched once per command run and shared across every concurrent target, since
+    the node roster does not change over the life of a single stop/run/update.
+    """
+    return {node.id: node.name for node in await client.nodes.list()}
+
+
+async def confirm_jobs(names: Sequence[str], *, verb: str) -> bool:
+    """Prompt the user to confirm a job action, returning True to proceed.
+
+    ``verb`` is the leading phrase (e.g. ``"Stop and PURGE"``); the shared wording
+    keeps the confirmation prompt identical across the commands that use it.
+    """
+    joined = ", ".join(names)
+    answer = await select_one(
+        [("Yes", True), ("No", False)],
+        f"{verb} {len(names)} job(s): {joined}?",
+    )
+    return bool(answer)
+
+
+def final_panel_title[O](
+    outcomes: list[O], seconds: float, *, verb: str, succeeded: Callable[[O], bool]
+) -> str:
+    """Build the live panel's final title from the ordered outcomes and elapsed time.
+
+    Counts the outcomes ``succeeded`` marks as clean so the title reads ``Deployed 2
+    jobs`` or the ``1 of 2 jobs`` partial form. ``verb`` is the past-tense summary
+    word each command supplies.
+    """
+    ok = sum(1 for o in outcomes if succeeded(o))
+    return summary_title(verb, done=ok, total=len(outcomes), seconds=seconds)
+
+
+def report_outcomes[O](  # noqa: PLR0913
+    outcomes: list[O],
+    *,
+    name_of: Callable[[O], str],
+    detail_of: Callable[[O], str],
+    is_warn: Callable[[O], bool],
+    is_fail: Callable[[O], bool],
+    fail_verb: str,
+    warn_fallback: str = "",
+    warnings_of: Callable[[O], str] | None = None,
+) -> None:
+    """Emit a durable log line for every outcome that did not finish cleanly.
+
+    The live panel is transient on a pipe or in CI, so each timed-out or failed
+    outcome is echoed here: a warning for ``is_warn`` outcomes (falling back to
+    ``warn_fallback`` when the outcome carries no detail) and an error reading
+    ``<name> failed to <fail_verb>`` for ``is_fail`` outcomes. When ``warnings_of``
+    is supplied, any non-empty register warning is surfaced as its own line.
+    """
+    for outcome in outcomes:
+        if is_warn(outcome):
+            pp.warning(f"{name_of(outcome)}: {detail_of(outcome) or warn_fallback}")
+        elif is_fail(outcome):
+            detail = detail_of(outcome)
+            pp.error(
+                f"{name_of(outcome)} failed to {fail_verb}",
+                details=[detail] if detail else None,
+            )
+        if warnings_of is not None and (warnings := warnings_of(outcome)):
+            pp.warning(f"{name_of(outcome)}: {warnings}")
+
+
+def ok_row(label: str) -> tuple[str, str]:
+    """Build a finished-row ``(glyph, label)`` for a clean success outcome."""
+    return (OUTCOME_GLYPH["ok"], f"[green]{label}[/]")
+
+
+def warn_row(label: str) -> tuple[str, str]:
+    """Build a finished-row ``(glyph, label)`` for a warning outcome."""
+    return (OUTCOME_GLYPH["warn"], f"[yellow]{label}[/]")
+
+
+def fail_row(label: str) -> tuple[str, str]:
+    """Build a finished-row ``(glyph, label)`` for a failure outcome."""
+    return (OUTCOME_GLYPH["fail"], f"[red]{label}[/]")

{nomadctl-0.2.0 → nomadctl-0.4.0}/src/nd/commands/exec.py

@@ -32,7 +32,7 @@ def exec_(
     job: Annotated[
         str | None,
         typer.Argument(
-            help="Running job to enter; matches any job whose name starts with this. "
+            help="Running job to enter; matches any job whose name contains this. "
             "Omit to pick from a list."
         ),
     ] = None,

{nomadctl-0.2.0 → nomadctl-0.4.0}/src/nd/commands/logs.py

@@ -29,7 +29,7 @@ def logs(  # noqa: PLR0913
     job: Annotated[
         str | None,
         typer.Argument(
-            help="Running job to read; matches any job whose name starts with this. "
+            help="Running job to read; matches any job whose name contains this. "
             "Omit to pick from a list."
         ),
     ] = None,

{nomadctl-0.2.0 → nomadctl-0.4.0}/src/nd/commands/plan.py

@@ -30,8 +30,7 @@ def plan(
     job: Annotated[
         str | None,
         typer.Argument(
-            help="Job to plan; matches any job whose name starts with this. "
-            "Omit to pick from a list."
+            help="Job to plan; matches any job whose name contains this. Omit to pick from a list."
         ),
     ] = None,
     dry_run: Annotated[  # noqa: FBT002

{nomadctl-0.2.0 → nomadctl-0.4.0}/src/nd/commands/run.py

@@ -14,15 +14,21 @@ from nclutils import pp
 
 from nd.binary import NomadBinary, NomadBinaryError
 from nd.commands._common import VerboseOption, configure_verbosity
+from nd.commands._orchestration import (
+    fail_row,
+    final_panel_title,
+    node_names_by_id,
+    ok_row,
+    report_outcomes,
+    warn_row,
+)
 from nd.constants import DEPLOY_TIMEOUT_SECONDS, HEALTHY_ALLOC_STATUSES, POLL_INTERVAL_SECONDS
 from nd.jobfiles import candidates_for, discover_job_files, load_job_directories
 from nd.nomad import NomadClient, NomadConfig
-from nd.nomad.errors import NomadError
+from nd.nomad.errors import NomadDecodeError, NomadError
 from nd.targets import resolve_targets, select_candidates
 from nd.ui.alloc_rows import alloc_children
-from nd.ui.duration import summary_title
 from nd.ui.live_panel import PanelUpdate, run_rows
-from nd.ui.styles import OUTCOME_GLYPH
 
 if TYPE_CHECKING:
     from nd.jobfiles import JobCandidate
@@ -106,10 +112,12 @@ def _task_role(lifecycle: dict[str, object] | None, index: int) -> tuple[int, st
     return (1_000 + index, "main")
 
 
+# Outcome labels carry the same color as their glyph so the status word reads as
+# success/failure at a glance, not just the leading mark.
 _OUTCOME_ROW: dict[DeployStatus, tuple[str, str]] = {
-    DeployStatus.DEPLOYED: (OUTCOME_GLYPH["ok"], "deployed"),
-    DeployStatus.FAILED: (OUTCOME_GLYPH["fail"], "failed"),
-    DeployStatus.TIMEOUT: (OUTCOME_GLYPH["warn"], "still deploying"),
+    DeployStatus.DEPLOYED: ok_row("deployed"),
+    DeployStatus.FAILED: fail_row("failed"),
+    DeployStatus.TIMEOUT: warn_row("still deploying"),
 }
 
 
@@ -130,7 +138,7 @@ def run(
     job: Annotated[
         str | None,
         typer.Argument(
-            help="Job to run; matches any not-running job whose name starts with this. "
+            help="Job to run; matches any not-running job whose name contains this. "
             "Omit to pick from a list."
         ),
     ] = None,
@@ -251,7 +259,7 @@ async def _deploy_all(
         Ordered list of outcomes, one per target.
     """
     # Resolve node IDs to names once so every job's detail rows can show placement.
-    node_names = {node.id: node.name for node in await client.nodes.list()}
+    node_names = await node_names_by_id(client)
 
     async def do_work(candidate: JobCandidate, update: PanelUpdate) -> DeployOutcome:
         return await _deploy_one(
@@ -268,20 +276,27 @@ async def _deploy_all(
         final_title=_final_title,
     )
 
-    for o in ordered:
-        if o.status is DeployStatus.TIMEOUT:
-            pp.warning(f"{o.name}: {o.detail or 'still deploying'}")
-        elif o.status is DeployStatus.FAILED:
-            pp.error(f"{o.name} failed to deploy", details=[o.detail] if o.detail else None)
-        if o.warnings:
-            pp.warning(f"{o.name}: {o.warnings}")
+    report_outcomes(
+        ordered,
+        name_of=lambda o: o.name,
+        detail_of=lambda o: o.detail,
+        is_warn=lambda o: o.status is DeployStatus.TIMEOUT,
+        is_fail=lambda o: o.status is DeployStatus.FAILED,
+        fail_verb="deploy",
+        warn_fallback="still deploying",
+        warnings_of=lambda o: o.warnings,
+    )
     return ordered
 
 
 def _final_title(outcomes: list[DeployOutcome], elapsed_seconds: float) -> str:
     """Build the final panel title with deployed totals and elapsed seconds."""
-    ok = sum(1 for o in outcomes if o.status is DeployStatus.DEPLOYED)
-    return summary_title("Deployed", ok, len(outcomes), elapsed_seconds)
+    return final_panel_title(
+        outcomes,
+        elapsed_seconds,
+        verb="Deployed",
+        succeeded=lambda o: o.status is DeployStatus.DEPLOYED,
+    )
 
 
 async def _deploy_one(
@@ -316,8 +331,13 @@ async def _deploy_one(
         lifecycle = task_lifecycle(body)
         update("registering")
         resp = await client.jobs.register(body)
-        outcome = await _watch(
-            client, candidate.name, node_names=node_names, lifecycle=lifecycle, update=update
+        outcome = await watch_deploy(
+            client,
+            candidate.name,
+            node_names=node_names,
+            lifecycle=lifecycle,
+            update=update,
+            since_index=resp.job_modify_index,
         )
         # Attach any register warnings so the caller can surface them after the panel closes.
         return replace(outcome, warnings=resp.warnings)
@@ -325,13 +345,14 @@ async def _deploy_one(
         return DeployOutcome(candidate.name, DeployStatus.FAILED, str(exc))
 
 
-async def _watch(
+async def watch_deploy(
     client: NomadClient,
     job_id: str,
     *,
     node_names: dict[str, str],
     lifecycle: TaskLifecycle,
     update: PanelUpdate,
+    since_index: int = 0,
 ) -> DeployOutcome:
     """Poll a registered job until its deployment (or allocations) settle or time out.
 
@@ -346,27 +367,47 @@ async def _watch(
         node_names: Map of node ID to node name for the per-allocation detail rows.
         lifecycle: Task ordering and labels from the compiled job spec.
         update: Callback to update the live panel phase text and detail rows.
+        since_index: The ``JobModifyIndex`` from this registration. Deployments
+            created before it belong to a previous run and are ignored so a re-run
+            of a dead job is not reported as instantly deployed off a stale record.
 
     Returns:
         The terminal deploy outcome for this job.
     """
     deadline = time.monotonic() + DEPLOY_TIMEOUT_SECONDS
     while True:
-        allocs = await client.jobs.allocations(job_id)
-        children = alloc_children(allocs, node_names, lifecycle)
-        deployments = await client.jobs.deployments(job_id)
-        if deployments:  # service job: follow the most-recent deployment
-            dep = await client.deployments.read(deployments[0].id)
-            if dep.status == _DEPLOY_SUCCESS:
-                return DeployOutcome(job_id, DeployStatus.DEPLOYED)
-            if dep.status in _DEPLOY_FAILURE:
-                return DeployOutcome(job_id, DeployStatus.FAILED, dep.status_description)
-            update(deploy_phase(dep), children)
-        else:  # batch/system job: follow allocations
-            running = sum(1 for a in allocs if a.client_status in HEALTHY_ALLOC_STATUSES)
-            if allocs and running == len(allocs):
-                return DeployOutcome(job_id, DeployStatus.DEPLOYED)
-            update(f"placing {running}/{len(allocs) or '?'} allocs", children)
+        try:
+            allocs = await client.jobs.allocations(job_id)
+            deployments = await client.jobs.deployments(job_id)
+            # The plural endpoint's ordering is undocumented, so pick this run's
+            # deployment by index rather than trusting position. A job that has ever
+            # run keeps its prior deployments listed; ignoring those created before
+            # this registration is what stops a stale "successful" record from
+            # ending the watch the instant a dead job is re-run.
+            mine = [d for d in deployments if d.create_index >= since_index]
+            latest = max(mine, key=lambda d: d.create_index) if mine else None
+            dep = await client.deployments.read(latest.id) if latest else None
+        except NomadDecodeError as exc:
+            # A freshly-placed allocation can momentarily serialize in a shape we
+            # cannot decode (e.g. TaskStates: null before its tasks start). Skip
+            # this tick and retry rather than failing an otherwise-healthy deploy;
+            # the deadline below is the backstop if it never recovers.
+            pp.debug(f"{job_id}: skipping poll after transient decode error: {exc}")
+        else:
+            children = alloc_children(allocs, node_names, lifecycle)
+            if dep is not None:  # service job: follow this run's deployment
+                if dep.status == _DEPLOY_SUCCESS:
+                    return DeployOutcome(job_id, DeployStatus.DEPLOYED)
+                if dep.status in _DEPLOY_FAILURE:
+                    return DeployOutcome(job_id, DeployStatus.FAILED, dep.status_description)
+                update(deploy_phase(dep), children)
+            elif deployments:  # service job whose new deployment has not appeared yet
+                update("registering", children)
+            else:  # batch/system job: follow allocations
+                running = sum(1 for a in allocs if a.client_status in HEALTHY_ALLOC_STATUSES)
+                if allocs and running == len(allocs):
+                    return DeployOutcome(job_id, DeployStatus.DEPLOYED)
+                update(f"placing {running}/{len(allocs) or '?'} allocs", children)
         if time.monotonic() >= deadline:
             return DeployOutcome(job_id, DeployStatus.TIMEOUT, "deploy still in progress")
         await asyncio.sleep(POLL_INTERVAL_SECONDS)