BREAKING: canonical --timeout everywhere; remove prepare --force alias

CHANGELOG.md

@@ -58,6 +58,32 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
   explicit `array_tasks` modifier, and using `array_tasks` without `x-slurm.array`
   is rejected.
 
+### Changed
+
+- **BREAKING:** every per-command "give up after this long" flag is now spelled
+  `--timeout` and takes a DURATION string (`30s`, `5m`, `1h`, or a bare number
+  of seconds). The old spellings are removed outright (no hidden aliases), and
+  each command's default is unchanged:
+
+  | Command | Before | After | Default |
+  | --- | --- | --- | --- |
+  | `test` | `--wait-timeout <DURATION>` (alias `--timeout`) | `--timeout <DURATION>` | `180s` |
+  | `notebook` | `--ready-timeout <DURATION>` | `--timeout <DURATION>` | `10m` |
+  | `germinate` | `--pending-timeout <DURATION>` | `--timeout <DURATION>` | `30m` |
+  | `when` | `--timeout <DURATION>` | unchanged | none |
+  | `sweep observe` | `--timeout <DURATION>` | unchanged | none |
+  | `doctor mpi-smoke` / `fabric-smoke` / `readiness` | `--timeout-seconds <SECONDS>` | `--timeout <DURATION>` | `5m` (was `300` seconds; same duration) |
+
+  `doctor --timeout` still accepts a bare number of seconds, so
+  `--timeout-seconds 300` migrates to `--timeout 300` (or `--timeout 5m`).
+
+### Removed
+
+- **BREAKING:** the hidden deprecated `prepare --force` alias for
+  `prepare --force-rebuild` is gone; `prepare --force` is now an unknown-flag
+  error. `--force` now means only "overwrite the output file" (`new`/`evolve`)
+  everywhere in the CLI. Use `prepare --force-rebuild`.
+
 ## [0.1.52] - 2026-06-30
 
 ### Fixed

docs/src/cli-reference.md

@@ -302,14 +302,14 @@ Settings profiles can also configure these via `[defaults.binaries]` or `[profil
 ```bash
 hpc-compose germinate -f compose.yaml
 hpc-compose germinate -f compose.yaml --canary-time 00:01:00 --metrics-interval 5
-hpc-compose germinate -f compose.yaml --pending-timeout 30m --format json
+hpc-compose germinate -f compose.yaml --timeout 30m --format json
 ```
 
 Useful options:
 
 - `--canary-time <TIME>` defaults to `00:01:00`.
 - `--metrics-interval <SECONDS>` defaults to `5` and is forced on in the canary plan.
-- `--pending-timeout <DURATION>` defaults to `30m`.
+- `--timeout <DURATION>` defaults to `30m`.
 - `--min-cpus <N>`, `--min-mem <MEM>`, and `--min-gpus <N>` set canary floors.
 - `--dry-run` renders the canary script without calling `sbatch`.
 - `--skip-prepare`, `--force-rebuild`, `--keep-failed-prep`, `--no-preflight`, and `--script-out` match the normal preparation flags.
@@ -457,7 +457,7 @@ Useful `test` options:
 | `--local` | Run the finite smoke spec through the local supervisor. |
 | `--submit` | Submit the finite smoke spec to Slurm; required before any scheduler submission happens. |
 | `--time <TIME>` | Override Slurm wall time for `--submit`; defaults to `00:01:00`. |
-| `--wait-timeout <DURATION>` (alias `--timeout`) | Stop waiting and best-effort cancel/cleanup after the timeout; defaults to `180s`. |
+| `--timeout <DURATION>` | Stop waiting and best-effort cancel/cleanup after the timeout; defaults to `180s`. |
 | `--format json` | Emit phase status, job id, script path, per-service results, and failure reason for automation. |
 
 `dev` is local-only and watches host directories from service `volumes`:
@@ -539,7 +539,7 @@ It calls `srun --pty` directly with Pyxis `--container-image` and defaults to `b
 ```bash
 hpc-compose notebook [--kind jupyter|vscode] [--image IMAGE] [--port N] [--token TOKEN]
                      [--volume HOST:CONTAINER]... [--working-dir PATH] [--tunnel-name NAME]
-                     [--ready-timeout DURATION] [--follow] [--dry-run] [--local] [-- ARGS...]
+                     [--timeout DURATION] [--follow] [--dry-run] [--local] [-- ARGS...]
                      [--resources NAME] [--time T] [--mem M] [--cpus-per-task N] [--gpus N]
                      [--partition P] [--env K=V]
 ```

docs/src/notebook.md

@@ -98,7 +98,7 @@ For VS Code, `code tunnel` performs GitHub device-flow authentication the first
 
 - **Images and users.** `jupyter/scipy-notebook` runs as the non-root `jovyan` user. Bind-mounted host directories must be writable by that user (typically uid 1000). Use `--working-dir` to point at your mounted workspace and adjust ownership on the host if needed.
 - **VS Code images.** There is no universal default `code` image; supply one with `--image` that contains the VS Code CLI.
-- **Readiness.** `hpc-compose` waits for a log pattern (`/lab?token=` for Jupyter, `vscode.dev/tunnel/` for VS Code) before printing the URL. Use `--ready-timeout` (default `10m`) to bound the wait; first-run image pulls happen during `prepare`, before the readiness clock starts.
+- **Readiness.** `hpc-compose` waits for a log pattern (`/lab?token=` for Jupyter, `vscode.dev/tunnel/` for VS Code) before printing the URL. Use `--timeout` (default `10m`) to bound the wait; first-run image pulls happen during `prepare`, before the readiness clock starts.
 - **Declarative counterpart.** The same workflow is available as a compose file via the `jupyter` template (`hpc-compose new --template jupyter`), so you can commit it to a repo and launch with `hpc-compose up`.
 
 ## Related Docs

man/man1/hpc-compose-doctor-fabric-smoke.1

@@ -29,8 +29,8 @@ Submit the fabric smoke probe to Slurm; without this, only render/explain it.
 \fB--script\-out\fR \fIOUTPUT\fR
 Write the rendered fabric smoke batch script to this path.
 .TP
-\fB--timeout\-seconds\fR \fISECONDS\fR
-Timeout for a submitted fabric smoke job. Default: 300.
+\fB--timeout\fR \fIDURATION\fR
+Timeout for a submitted fabric smoke job. Default: 5m.
 .TP
 \fB--color\fR \fIWHEN\fR
 Controls colored output. Default: auto. Possible values: auto, always, never.

man/man1/hpc-compose-doctor-mpi-smoke.1

@@ -26,8 +26,8 @@ Submit the MPI smoke probe to Slurm; without this, only render/explain it.
 \fB--script\-out\fR \fIOUTPUT\fR
 Write the rendered MPI smoke batch script to this path.
 .TP
-\fB--timeout\-seconds\fR \fISECONDS\fR
-Timeout for a submitted MPI smoke job. Default: 300.
+\fB--timeout\fR \fIDURATION\fR
+Timeout for a submitted MPI smoke job. Default: 5m.
 .TP
 \fB--color\fR \fIWHEN\fR
 Controls colored output. Default: auto. Possible values: auto, always, never.

man/man1/hpc-compose-doctor-readiness.1

@@ -26,7 +26,7 @@ Run the readiness probe from the current host instead of only explaining it.
 \fB--log\-file\fR \fIPATH\fR
 Log file to inspect for readiness.type=log when \-\-run is used.
 .TP
-\fB--timeout\-seconds\fR \fISECONDS\fR
+\fB--timeout\fR \fIDURATION\fR
 Override the probe timeout for this doctor run only.
 .TP
 \fB--color\fR \fIWHEN\fR

man/man1/hpc-compose-germinate.1

@@ -47,7 +47,7 @@ Walltime for the canary allocation. Default: 00:01:00.
 \fB--metrics\-interval\fR \fISECONDS\fR
 Metrics sampler interval forced into the canary plan. Default: 5.
 .TP
-\fB--pending\-timeout\fR \fIDURATION\fR
+\fB--timeout\fR \fIDURATION\fR
 Give up if the canary remains non\-terminal for this long. Default: 30m.
 .TP
 \fB--min\-cpus\fR \fICPUS\fR

man/man1/hpc-compose-notebook.1

@@ -32,7 +32,7 @@ Container working directory.
 \fB--tunnel\-name\fR \fINAME\fR
 VS Code tunnel name. Default: hpc\-compose.
 .TP
-\fB--ready\-timeout\fR \fIDURATION\fR
+\fB--timeout\fR \fIDURATION\fR
 Give up waiting for the notebook to become ready after this duration. Default: 10m.
 .TP
 \fB--follow\fR

man/man1/hpc-compose-test.1

@@ -47,7 +47,7 @@ Submit the smoke test to Slurm.
 \fB--time\fR \fITIME\fR
 Walltime override for \-\-submit smoke tests. Default: 00:01:00.
 .TP
-\fB--wait\-timeout\fR \fIDURATION\fR
+\fB--timeout\fR \fIDURATION\fR
 Maximum time to wait for the smoke test to reach a terminal result. Default: 180s.
 .TP
 \fB--script\-out\fR \fIOUTPUT\fR

src/cli/commands.rs

@@ -300,12 +300,6 @@ pub enum Commands {
             help = "Refresh imported and prepared artifacts before running"
         )]
         force_rebuild: bool,
-        #[arg(
-            long = "force",
-            hide = true,
-            help = "Deprecated alias for --force-rebuild"
-        )]
-        force_deprecated: bool,
         #[arg(long, value_enum, value_name = "FORMAT", help = "Output format")]
         format: Option<OutputFormat>,
     },
@@ -611,12 +605,12 @@ pub enum Commands {
         script_out: Option<PathBuf>,
         #[arg(
             long,
-            value_name = "SECONDS",
-            default_value_t = 300,
+            value_name = "DURATION",
+            default_value = "5m",
             help = "Timeout for a submitted MPI smoke job",
             hide = true
         )]
-        timeout_seconds: u64,
+        timeout: String,
         #[arg(
             long,
             value_name = "PATH",
@@ -893,7 +887,7 @@ pub enum Commands {
             default_value = "30m",
             help = "Give up if the canary remains non-terminal for this long"
         )]
-        pending_timeout: String,
+        timeout: String,
         #[arg(
             long,
             value_name = "CPUS",
@@ -985,13 +979,12 @@ pub enum Commands {
         )]
         time: String,
         #[arg(
-            long = "wait-timeout",
-            alias = "timeout",
+            long,
             value_name = "DURATION",
             default_value = "180s",
             help = "Maximum time to wait for the smoke test to reach a terminal result"
         )]
-        wait_timeout: String,
+        timeout: String,
         #[arg(
             long,
             value_name = "OUTPUT",
@@ -2254,7 +2247,7 @@ pub enum Commands {
             default_value = "10m",
             help = "Give up waiting for the notebook to become ready after this duration"
         )]
-        ready_timeout: String,
+        timeout: String,
         #[arg(
             long,
             help = "Stream service logs after readiness instead of detaching"
@@ -2724,11 +2717,11 @@ pub enum DoctorCommands {
         script_out: Option<PathBuf>,
         #[arg(
             long,
-            value_name = "SECONDS",
-            default_value_t = 300,
+            value_name = "DURATION",
+            default_value = "5m",
             help = "Timeout for a submitted MPI smoke job"
         )]
-        timeout_seconds: u64,
+        timeout: String,
     },
     #[command(about = "Render or run MPI and fabric smoke probes for one service")]
     FabricSmoke {
@@ -2761,11 +2754,11 @@ pub enum DoctorCommands {
         script_out: Option<PathBuf>,
         #[arg(
             long,
-            value_name = "SECONDS",
-            default_value_t = 300,
+            value_name = "DURATION",
+            default_value = "5m",
             help = "Timeout for a submitted fabric smoke job"
         )]
-        timeout_seconds: u64,
+        timeout: String,
     },
     #[command(about = "Explain or run one service readiness probe from the current host")]
     Readiness {
@@ -2792,10 +2785,10 @@ pub enum DoctorCommands {
         log_file: Option<PathBuf>,
         #[arg(
             long,
-            value_name = "SECONDS",
+            value_name = "DURATION",
             help = "Override the probe timeout for this doctor run only"
         )]
-        timeout_seconds: Option<u64>,
+        timeout: Option<String>,
     },
 }
 

src/commands/doctor.rs

@@ -68,7 +68,7 @@ pub(crate) fn doctor_mpi_smoke(
     quiet: bool,
 ) -> Result<()> {
     if submit && timeout_seconds == 0 {
-        bail!("doctor --mpi-smoke --timeout-seconds must be at least 1 when --submit is used");
+        bail!("doctor --mpi-smoke --timeout must be at least 1s when --submit is used");
     }
     let output_format = output::resolve_output_format(format);
     let plan = load::load_plan_with_interpolation_vars_cache_default_and_resource_profiles(
@@ -284,7 +284,7 @@ pub(crate) fn doctor_fabric_smoke(
         quiet,
     } = options;
     if submit && timeout_seconds == 0 {
-        bail!("doctor --fabric-smoke --timeout-seconds must be at least 1 when --submit is used");
+        bail!("doctor --fabric-smoke --timeout must be at least 1s when --submit is used");
     }
     let selected_checks = FabricCheckSelection::parse(checks.as_deref())?;
     let output_format = output::resolve_output_format(format);
@@ -511,7 +511,7 @@ pub(crate) fn doctor_readiness(
     quiet: bool,
 ) -> Result<()> {
     if matches!(timeout_seconds, Some(0)) {
-        bail!("doctor readiness --timeout-seconds must be at least 1");
+        bail!("doctor readiness --timeout must be at least 1s");
     }
     let output_format = output::resolve_output_format(format);
     let plan = load::load_plan_with_interpolation_vars_cache_default_and_resource_profiles(